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ABSTRACT 


This  symposium  was  organized  to  introduce  the  Government  ADP  community  to 
the  concepts  of  when  and  how  to  apply  the  government-wide  guidelines  of  FTPS 
PUB  38  "Guidelines  for  Documentation  of  Computer  Programs  and  Automated  Data 
Systems"  -  in  developing  both  agency  standards  and  operational 
documentation.  The  proceedings  contain  all  of  the  papers  presented  in  the 
plenary  session,  and  the  papers  plus  summaries  of  question  and  answer 
sessions  presented  in  three  parallel  sessions  for  management,  operations, 
and    staff  attendees. 
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PREFACE 


The  planning,  design,  development,  and  implementation  of  computer  programs 
and  automated  data  systems  (software)  represent  a  considerable  investment  of 
human  and  automated  resources.  To  maximize  the  return  on  this  investment, 
and  to  provide  for  cost-effective  operation,  revision,  and  maintenance, 
sufficient  documentation  is  needed  in  each  stage  of  the  software  development 
life  cycle.  FIPS  PUB  38  was  prepared  to  provide  Government-wide  guidelines 
in  response  to  that  need.  In  order  to  introduce  the  government  ADP 
community  to  the  concepts  of  FIPS  PUB  38,  FIPS  Task  Group  14  (Documentation 
for  Information  Processing  Standards)  organized  a  symposium  to  provide 
attendees  with  a  fuller  understanding  of  when  and  how  to  apply  these 
government-wide  guidelines  in  developing  agency  standards  or  operational 
documentation.      That    symposium   is   documented    in   these  proceedings. 


Because  the  publication  process  is  already  longer  than  it  should  have  been, 
the  authors  have  not  had  an  opportunity  to  review  the  results  of  my  editing. 
I  accept  responsibility  for  any  change  in  meaning  which  this  process  may 
have    inadvertently   introduced.      My   editing   was    limited  to: 

Style  -  I  imposed  a  degree  of  consistency  to  different  references  to  the 
same   subject    (for   example,    four  different  ways   of  writing   "FIPS  PUB  38"; 

Clarity  -  I  tried  to  untangle  some  grammatical  constructions  which,  while 
acceptable   in  an  oral   presentation,    are   cumbersome  or   confusing  on  paper; 

Space  -  in  a  few  cases,  I  shortened  sentences  here  and  there  to  keep  a  paper 
from   ending  with   only   two   or    three    lines   on   the   past  page. 


One  of  the  purposes  FIPS  TG  14  had  in  mind  for  this  symposium  was  to  open 
channels  for  feedback  on  FIPS  PUB  38  from  the  attendees.  Only  time  can  tell 
how  well  that  purpose  was  achieved.  Meanwhile,  FIPS  TG  14  is  developing 
guidelines  for  other  document  types.  Included  in  the  list,  as  of  this 
writing,  are:  Project  Request,  Project  Notebook,  Project  Development  Plan, 
Pos t- Ins t a  1 1  a t i on  Evaluation  Report,  System  Development  Ac t iv i ty /Tas k 
Report,  Feasibility  Analysis  Document,  and  Cost/Benefit  Analysis  Document, 
Readers  who  are  interested  in  working  on  any  of  these  projects,  or  who  can 
suggest  additional  ones,  may  contact  any  TG-14  member,  or  the  office  of  the 
Associate   Director    (of   NBS)    for   ADP    Standards,    (301)  921-3157. 

On  behalf  of  FIPS  TG  14,  I  wish  to  express  appreciation  to  the  speakers  and 
panelists,  who  contributed  so  much  of  their  time  and  effort  to  this 
symposium;  to  the  National  Bureau  of  Standards,  for  administrative  and 
logistical  support,  which  made  the  symposium  run  smoothly;  and  to  the  Civil 
Service  Commission,  which  was  extremely  helpful  in  the  final  planning  for 
and  announcing  of  this  symposium.  Mark  Silverman,  Roy  Young,  and  I  had  all 
the  fun  of  putting  it  together,  while  all  these  others  had  all  the  work. 
Finally,  this  symposium  could  not  have  been  successful  without  the 
wholehearted  support  of  the  nearly  300  attendees,  without  whom  the  whole 
thing  would   have   been  pointless.      We   thank  you  very  much. 

On  a  final,  personal  note,  I  wish  to  thank  all  the  secretaries  who  typed 
their  bosses'  speeches,  and  got  them  to  me  by  the  deadline.  By  the  time  I 
had  edited  the  first  few,  I  realized  that  they'd  all  have  to  be  retyped.  My 
own  secretary,  Mrs.  Karen  V,  Warraus,  has  done  an  outstanding  job,  and  has 
helped  me   tremendously   in   this  undertaking. 

March   24,    1977  Mitchell   A.    Krasny,  Editor 

Springfield,    Va   22161  National   Technical   Information  Service 

iv 


TABLE   OF  CONTENTS 


ABSTRACT    &  KEYWORDS 
PREFACE 

TABLE   OF  CONTENTS 

INTRODUCTION 

Mark  Silverman 
WELCOME  ADDRESS 

M.   Zane  Thornton 
WHY  DOCUMENT? 

Theodore   D.  Puckorius 
THE   PHILOSOPHY   OF  FIPS   PUB   38   -  AN  INTRODUCTION 

Jame s  Gillespie 
LIFE    CYCLE    CONCEPTS   AND   DOCUMENT  TYPES 

Roy  A.  Young 

FLEXIBILITY   PROVISIONS   AND   DOCUMENT   TYPE  SELECTION 

Robert   R,  Hegland 
CONTENT  GUIDELINES 

Thomas  M,  Kurihara 
DESCRIPTION   OF   AFTERNOON  SESSIONS 

Mark  Silverman 

SESSION  A 

USDA   APPLICATION  MANAGEMENT 

Robert   V.  Head 
DOCUMENTATION   STANDARDS   -   A  MANAGEMENT  VIEW 

Eugene   B.  Smith 
KEY   ELEMENTS   IN   THE    ADP    SYSTEM   DEVELOPMENT   PROCESS   AT  HUD 

Dr.   Marvin  Goer 
SYNOPSIS   OF   QUESTIONS   AND   ANSWERS   FROM   PARALLEL   SESSION  A 

Greg  Loss  and   Tom  Kurihara 

SESSION  B 

INTRODUCTION:    ADP   SYSTEMS,    OPERATIONS,    AND   PROGRAMMER  PERSONNEL 

Thomas  Giammo 
PROBLEMS    IN   USING   THE    DOCUMENTATION  GUIDELINE 

Robert   R.  Hegland 
SYNOPSIS   OF  QUESTIONS   AND  ANSWERS   FROM  PARALLEL   SESSION  B 

Robert   A.   Mattes   and  Kenneth  Rodey 

SESSION  C 

INTRODUCTION:    "STANDARDS,    TRAINING,    POLICY   AND   AUDIT  PERSONNEL" 

Harris  G.  Reiche 
FIPS   PUB   38    -   IMPLEMENTATION   PHILOSOPHY    IN  HEW 

Joseph  J.  Strnad 
THE   ROLE   OF   THE   AUDITORS    IN   THE    DEVELOPMENT    &   EVALUATION  OF 
AUTOMATED  SYSTEMS 

Phillip   L.  Morrison 
SYNOPSIS   OF   QUESTIONS    AND   ANSWERS   FROM   PARALLEL   SESSION  C 

Fred   J,    Cole   and   Edie  Lasner 

FIPS   TASK   GROUP    14   MEMBERSHIP    &    SYMPOSIUM  PLANNING  COMMITTEE 
BIBLIOGRAPHIC   DATA  SHEET 


V 


INTRODUCTION 


Mark   Silverman,  Sympos 


ium  Cha 
s  i  s  t  an  t 
Survey 
1  Stop 
22092 


irman 


Technical    Staff  As 
U.    S.  Geological 


National    Center,  Mai 
Reston,  Virginia 


801 


Welcome  to  the  Symposium  for  Documentation  of  Computer  Programs  and 
Automated  Data  Systems,  which  is  being  held  to  afford  attendees  a  better 
understanding  of  FIPS  PUB  38.  FIPS  Task  Group  14  developed  FTPS  PUB  38  as  a 
set  of  guidelines  for  Government-wide  use  to  meet  the  need  for  adequate  and 
consistent  documentation  during  the  development  stage  of  a  software  system's 
life   cycle . 

The  life  cycle  of  a  software  system  includes  the  stages  of  planning,  design, 
development,  implementation,  and  maintenance.  Each  of  these  stages  may 
require   a   substantial    investment    in   time   and    other  resources. 

This  symposium  should  help  attendees  apply  the  guidelines  in  FIPS  PUB  38  to 
reduce  costs  significantly.  We  hope  you  will  find  these  guidelines  helpful 
both  in  the  development  of  agency  standards  for  software  documentation  and 
in   documenting   computer   programs    and   automated   data  systems. 

And  now,  I  am  pleased  to  present  Mr.  M.  Zane  Thornton,  the  Deputy  Director 
of  the  Institute  for  Computer  Sciences  and  Technology,  the  National  Bureau 
of  Standards.  Mr.  Thornton  will  provide  some  background  on  the  FIPS  program 
and   introduce   our   distinguished   Keynote  speaker. 


WELCOME  ADDRESS 


M,    Zane  Thornton 
Deputy  Director 
Institute   for   Computer   Sciences   and  Technology 
National   Bureau  of  Standards 
Washington,   D.    C.  20234 


Good  morning,  Ladies  and  Gentlemen,  I  am  pleased  to  welcome  you  to  the 
National  Bureau  of  Standards  and  this  Symposium  on  the  Documentation  of 
Computer  Programs  and  Automated  Data  Systems.  Before  I  introduce  our 
keynote  speaker,  let  me  briefly  review  the  NBS  ADP  Standards  program  and 
the  Federal  Information  Processing  Standards  (or  FIPS)  activities  which 
produced  the  documentation  guidelines  which  are  the  subject  of  today's 
me  e  t  ing  . 

Since  enactment  of  Public  Law  89-306  (Brooks  Act),  the  National  Bureau  of 
Standards  has  had  a  leadership  role  in  the  management  of  activities  within 
the  Federal  Government  relating  to  the  development  and  maintenance  of 
uniform  Federal  automatic  data  processing  standards.  The  continuing 
objectives  of  the  NBS  ADP  Standards  Program  are  to  facilitate  the 
interchange  and  sharing  of  data,  programs,  and  equipment  by  Federal 
agencies;  to  improve  performance  and  quality  of  ADP  products  and  services 
developed  by  or  acquired  by  Federal  agencies;  and  to  make  Government  and 
industry  aware  of  the  need  for  standards  to  achieve  compatibility  and 
enhance  the  effective  utilization  of  ADP  products  and  services  in  the 
preparation  and   delivery  of  public  services. 

The  Federal  Information  Processing  Standards  program  sets  mandatory 
standards  for  the  Federal  ADP-communi ty .  In  carrying  out  this  program,  NBS 
has  maintained  close  cooperation  with  the  voluntary  standards  activities  of 
the  American  National  Standards  Institute  (ANSI)  and  the  International 
Organization  for  Standardization  (ISO),  NBS,  in  its  standards  management 
role,  is  responsible  for  assuring  Federal  participation  in  the  development 
of  ANSI  and  ISO  voluntary  standards,  for  considering  them  for  adoption  as 
Federal  standards  in  those  cases  where  they  meet  the  requirements  of  the 
Federal  Government,  or  for  initiating  independent  development  actions  in 
cases  where  ANSI  and   ISO  efforts   do  not   exist,    or   are   too  slow. 

The  NBS  FIPS  program  identifies  those  areas  in  which  ADP  standards  are 
needed,  pursues  their  development,  and  promulgates  the  completed  standards 
through  Federal  Information  Processing  Standards  Publication  (FIPS  PUBS). 
Presently  there  are  fourteen  active  FIPS  task  groups  with  over  350 
professional  participants  from  Government  and  industry,  addressing  such 
areas  as  programming  languages,  data  codes,  security  and  privacy,  network 
protocols,  and  documentation.  To  date,  44  standards,  guidelines,  and 
information  documents  have  been  developed  and  published  by  NBS  in  the  FIPS 
PUB  series.  The  current  standards  effort  addresses  four  major  areas:  (1) 
standards  that  provide  for  the  effective  interchange  and  sharing  of  data, 
programs,  and  equipment,  (2)  standards  to  increase  the  performance  and 
assure  quality  control  of  ADP  products  and  services;  (3)  standards  that 
facilitate  the  transfer  and  use  of  computer  technology  through  effective 
man-machine  interfaces;  and  (4)  standards  to  provide  for  the  safety  and 
security  of  personnel,  equipment,  and  data.  Priorities  are  given  those 
standardization  development  efforts  which  have  the  most  need  and  highest 
potential  benefit. 

In  June  1974,  in  a  letter  from  the  Director  of  NBS  to  the  Director  of  the 
General  Government  Division  of  the  General  Accounting  Office,  Documentation 
was  cited  as  one  of  the  highest  priority  subjects  in  the  Federal  ADP 
Standards  Program.  In  October  1974,  the  Comptroller  General  of  the  U.S.  in 
a  report  to  Congress  entitled  "Improvement  Needed  in  Documenting  Federal 
Computer   Systems"   affirmed   that   "Government   standards   are  not   available  to 
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assist  Federal  managers  in  deciding  what  type  of  documentation  to  prepare, 
how  much  to  prepare,  and  when  and  how  to  prepare  it."  The  report  noted  that 
"although  good  documentation  does  not  insure  successful  computer  op^erations, 
inadequate   documentation  can 

o  increase   the   cost   of   Federal  operations, 

o  weaken  management   control   of  ADP  systems, 

o  contribute    to    loss    of    funds    and   assets,  and 

o  limit    the   potential    for   sharing  programs." 

FIPS  Task  Group  14,  "Documentation  for  Information  Processing  Systems",  was 
established  in  March  1973,  and  charged  with  developing  standards  and 
guidelines  for  the  documentation  of  individual  computer  programs  and 
automated  data  systems.  This  task  group  is  composed  of  representatives  of 
more  than  twenty  Federal  agencies.  FIPS  PUB  38  is  one  of  the  products  of 
this  group.  Using  available  guidelines  from  various  Federal,  commercial, 
and  academic  organizations  as  points  of  departure,  the  group  selected  the 
best  features  of  the  best  of  these,  and  made  them  generally  applicable  to 
Federal  computer  installations.  FIPS  PUB  38,  which  you  have  as  part  of  your 
registration  packet,  has  been  extensively  reviewed,  revised  and  coordinated 
among   the   Federal    and   non-Federal   ADP  community. 

These  guidelines  for  Documentation  of  Computer  Programs  and  Automated  Data 
Systems  have  been  prepared  in  response  to  the  need  for  documentation  to 
support  the  effective  management  of  ADP  resources,  and  to  facilitate  the 
interchange    of   information  about    computer   software.      The   objectives   are  to: 

o     Provide   managers  with    technical   documents    to   review  at 
significant   development  milestones, 

o     Record    technical    information   to   allow   later   use  and 
modification   of  software, 

o     Facilitate   understanding   among  managers,  developers, 
programmers,    and   users    of  software, 

o     Increase    the   potential    for    transferability   and  sharing 
of   so  f  twar  e ,  and 

o     Provide   a   basis    for   auditability  of  software. 

Your   study   of   these   guidelines    today   should   help   achieve    these  goals. 

At  this  point,  I'd  like  to  thank  the  ADP  Management  Center  of  the  U.S.  Civil 
Service   Commission,    for   jointly   sponsoring    this    symposium  with  us. 

Now  it  gives  me  great  pleasure  to  introduce  our  featured  speaker,  Mr. 
Theodore   D.  Puckorius. 

Theodore  D.  Puckorius  was  appointed  Commissioner  of  the  General  Services 
Administration's  Automated  Data  and  Telecommunications  Service  (ADTS)  on  May 
19,  1975.  As  ADTS  Commissioner,  he  heads  an  organization  which  is 
responsible  for  centralized  management  of  general  purpose  data  processing 
and  support  services  for  all  Federal  agencies,  as  well  as  management  and 
operations  of  the  civilian  government's  telecommunications  system.  ADTS' 
operations  include  overall  procurement  responsibility  for  nearly  $800 
million  worth  of  ADP  hardware,  software,  services,  and  maintenance  annually; 
coordination,  consolidation,  and  collocation  of  Federal  requirements  to 
allow  maximum  utilization  and  sharing  of  government  com^)uter  resources; 
operation     of      three     Federal      Data     Processing   Centers   which   provide   a  full 


range  of  data  processing  services  for  individual  agencies;  an  inter-active 
timesharing  computer  system  which  permits  remote  access  service  nationwide; 
and  a  comprehensive,  multi-million  dollar  communications  network  which 
serves  Federal  agencies  across  the  nation  through  some  one  million  phones, 
over  10  million  miles  of  circuitry,  and  thousands  of  data  transmission 
devices , 

Prior  to  his  appointment  as  ADTS  Commissioner,  he  was  Vice  President  and 
Managing  Officer  of  the  Government  Services  Division  for  Lester  B.  Knight 
and  Associates,  Inc.  in  Chicago,  Illinois,  and  Washington,  D.  C.  Lester  B. 
Knight  is  a  Chicago-based  firm  specializing  in  management  consulting  and 
architectural/ engineering  services. 

From  1965  until  1971,  he  served  in  key  management  positions  with  Booz,  Allen 
and  Hamilton,  Inc.,  a  Chicago  consulting  firm.  Previously,  he  held 
increasingly  responsible  positions  with  North  American  Aviation  in  Columbus, 
Ohio;  AVCO  Electronics  and  Ordnance  Division  in  Cincinnati,  Ohio;  Hertz 
Corporation  in  Chicago,  Illinois;  and  the  Pillsbury  Company  in  Minneapolis, 
Minne  sota . 


Mr.  Puckorius  was  born  in  Chicago  on  April  7,  1930.  He  attended  DePaul 
University  and  received  a  Bachelor  of  Science  degree  with  honors  from  the 
University  of  Illinois.  He  has  done  graduate  work  in  financial  management 
and  production  management  at  the  University  of  Illinois  and  Ohio  State 
University.      He    is   a  veteran   of   the   United   States   Air  Force. 


Mr.  Puckorius  will  discuss  why  we  have  documentation  standards  and 
guidelines.      His    talk   is    titled:    "Why  Document?" 


WHY  DOCUMENT? 


Theodore   D.  Puckorius 
Commissioner,    Automated   Data   and   Telecommunications  Service 
General    Services  Administration 
18th   &  F   Streets,    NW,    Room  3240 
Washington,    D.    C.  20405 


Of  increasing  concern  in  the  past  few  years  has  been  technology  transfer 
which  implies  the  communication  of  some  technological  advancement  from  the 
innovators  to  those  who  need  the  information.  Technological  developments 
follow  one  another  at  a  furious  pace.  So  rapid  is  the  progress  that  the 
pioneers  in  one  area  run  the  risk  of  finding  that  what  they  are  perfecting 
at  great  expense  and  great  effort  is  also  being  perfected  in  another 
location,  likewise  with  great  expense  and  great  effort.  One  of  the 
particular  areas  of  technology  transfer  which  has  been  of  great  interest  is 
that  of  computer  software,  and  development  of  such  software  represents  a 
significant   portion   of    the   Federal   ADP  Budget. 

Fiscal  Year  1975  Federal  ADP  Inventory  shows  the  total  annual  cost  for  ADP 
in  the  government  to  be  approximately  $3.1  billion.  If  you  take  from  this 
figure  the  $850  million  spent  for  hardware  purchase  and  rental,  supplies  and 
site  preparation,  you  will  see  that  a  total  of  $2.25  billion  was  spent  on 
software  and  related  personnel  costs  alone.  That  is  approximately  three 
times  the  amount  of  all  other  ADP  related  costs  combined.  As  FTPS  PUB  38 
states      in    the    introduction:    "To   maximize    the    return   on    this    investmpntj  and 

to     provide      for      cost-effective     operation.  revision       and  maintenance, 

sufficient  documentation  is  needed  at  each  stage  of  the  software  development 
life  cycle". 

Documentation  is  essential  to  the  effective  development,  implementation, 
modification,  operation,  and  utilization  of  any  system.  Yet  this  is  a 
notoriously  weak  area  in  the  ADP  industry — and  one  in  which  there  are  few 
industry-wide      standards      or        guidelines.  Books        on       programming  and 

documentation  techniques  have  been  published  almost  since  the  first  program 
written  in  issachine  language;  and  large  organizations  and  institutions  have 
established  internal  standardization  requirements'.  Nevertheless,  no  one 
single  cohesive  agreement  on  documentation  has  been  reached  or  accepted  for 
widespread  usage.  Likewise,  funding  constraints,  tight  scheduling  and 
general  programmer  distaste  for  writing — have  generally  relegated  program 
documentation  to  the  lowest  priority.  As  a  result,  the  GAO  Study  on 
Automated  Decision  Making  indicates  there  is  much  room  for  improvement. 
Existing   standards    are   not   being   complied  with. 

Documentation  could  be  and  is  used  by  a  variety  of  ADP-industry  people 
during  the  initiation,  development  and  operation  phases  of  the  software  life 
cycle. 

systems    analysts    require    documentation    in   planning   new  systems 

programmers   need   documentation  when  writing  instructions 
to    implement    the   analysts'  plans 

.      management    needs    some    type    of    documentation  when  monitoring 
and    controlling    system   development   and  operations. 

auditors   need   documentation    in   evaluating   system  reliability 
and    in   advising  management   of   possible    system  shortcomings. 

The  documentation  used  by  these  people  can  be  categorized  into  four  major 
areas   of   application:    1)    user,    2)    system,    3)    program,    and   4)  operations. 
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There  are  many  levels  of  users  of  software  systems  with  differing 
information  needs  —  from  top  level  management,  through  operating  management, 
to  the  equipment  operator.  For  a  software  system  to  be  used  productively, 
instructions  and  aids  to  understanding  for  all  levels  of  intended  users  must 
be  provided  by   system  documentation. 

How   is    this   rather    limited   documentation   emp loyed   by   the  user? 

The  input-layout  and  completion  instructions  enable  the  user  to  comp le  te 
specified  documents  for  input  to  the  system.  The  output  report  definitions 
and  explanations  gives  the  user  the  basis  for  understanding  and  interpreting 
the  output.  Should  a  problem  develop  with  the  input,  the  error  correction 
procedures   provide   the   user   the  means   for  re-inputting  corrections. 


In     many   data   processing   applications    there    is   no   user   documentation  at  all. 

Input   documents   are   considered   to   be   self-explanatory — as     are     the  reports 

generated  by  the  system.  To  correct  errors — either  an  error  code  is 
issued — or   it   is   left   up   to   the   user   to   figure   out  his   own  mistake. 


Why  Document? 


Why,  indeed!!  Most  data  processing  systems  cost  substantial  amounts  of 
money,  manpower,  equipment,  and  time  to  develop.  They  were  developed  for 
utilization  by  user  departments.  But,  can  the  user  make  best  use  of  the 
system's    resources    and   potential   with    scant — or  worse   yet--no  documentation? 

For  effective  utilization  of  any  system,  the  user  must  understand  the 
purpose  of  the  system,  how  the  system  works — functionally — and  what  the 
system's  capabilities  are.  The  user  must  understand  how  the  capabilities 
can  be   most   effectively  utilized. 

System  documentation  in  most  data  processing  installations  ranks  as  the 
lowest  priority  in  the  already  low  priority  that  documentation  holds.  It  is 
therefore  usually  non-existent. 

System  documentation  should  exist  to  specify  for  the  analysts  and 
programmers--  the  requirement  s  —  the  operat  ing  ,  environment  —  the  design 
characteristics--   and   program   specifications    for   a  system. 

Documentation  should  exist,  but,  all  too  often,  much  unnecessary  work  and 
wasted  time  is  encountered  due  to  the  absence  of  documented  definitions  or 
detailed        specifications.  Many        changes       must      be     made     due      to  poor 

communication   and   poor   documentation   of   the   users'  needs. 


Essential  to  the  development  of  an  efficient  and  effective  system  are 
concrete  and  well  defined  job  objectives  and  specifications.  The  system 
analyst  (or  system  designer)  cannot  effectively  accomplish  his  end,  and 
supply  the  programming  staff  with  a  workable  detail  design  if  the  work  has 
had    to   come    from   inadequately   defined  objectives. 

The  problems  arising  from  a  lack  of  (or  poor)  system  documentation  magnify 
themselves  as  the  system  development  progresses.  Each  step  in  the  growth  of 
a  system  is  dependent  upon  the  accuracy  and  effectiveness  of  the  work  and 
documentation   of   the   preceding  steps. 


During  po s t- imp  1 emen t a t i on  review,  the  system  documentation  is  the  only 
valid  means  of  comparison  between  the  use-specifications  and  the  end 
results.  Without  it,  one  must  rely  upon  the  "best  recollections"  of 
individuals  involved.  Hopefully,  those  individuals  are  still  available  to 
query.  When  changes,  modifications,  or  maintenance  becomes  necessary,  the 
system  analysts  (designers)  and/or  programmers  must  rely  upon  their 
experience  with  the  system  (if  any)  or  piece  together  program  documentation 
(if     any),      unless      system     documentation     is      available.        This     makes  the 
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analyst/programmers'  jobs  not  only  difficult,  but  expensive — as  it  requires 
substantially  more  time  and  work  on  their  part  to  understand  the  current 
system--in  order  to  apply  changes.  Systems  documentation  is  important 
because  it  saves  both  time  and  money.  Similarly,  the  programmer  cannot 
design  and  program  efficiently  to  meet  the  user  needs  without  accurate  and 
detailed  specifications. 

Equally  important  to  both  the  maintenance  and  the  operations  staff  is  the 
programmer's  documentation.  Program  documentation  provides  the  maintenance 
programmers  with  the  knowledge  essential  for  effective  debugging  and 
implementation  of  enhancements  and  modifications.  Often  the  person 
maintaining  a  program  is  not  the  author.  Complete  program  documentation  is 
less  costly  in  man  hours  than  having  maintenance  programmers  wade  through 
source   codes    to   obtain   the   understanding   of   the   program   they  need. 

Documentation  provides  the  operations  personnel  with  the  specifications  and 
requirements   essential    to   planning   har dwar e / s o f twar e  needs. 

Operations  personnel  can  also  lend  valuable  expertise  in  terms  of 
hard war e / s o f twar e  utilization,  scheduling  requirements,  and  input/  output 
handling  in  the  system  design  stage  of  a  process.  Cooperation  between 
programming  and  operations  can  prove  a  valuable  asset  to  any  system 
deve 1 opmen  t . 


Why  Document? 

the 


Documentation  provides  the  means  for 
utilization   of    the    system  by    the  user. 


greatest      and     most  efficient 


Documentation  provides  the 
integration   of    the  system. 


means      for      careful,      well-planned      design  and 


Documentation  provides  the  maintenance  programmers  with  the  knowledge 
essential  for  effective  debugging  and  implementation  of  enhancements  and 
modifications. 

Documentation  provides  the  operations  personnel  with  the  specifications  and 
requirements  essential  to  planning  har dware / s o f twar e  needs  and  scheduling 
computer  utilization. 

Further,  documentation  provides  for  successful  and  cost  effective  sharing. 
The  recently  established  Software  Exchange  program  by  ADTS  provides  for  the 
sharing  of  computer  programs  developed  by  one  organization  for  use  by 
another  organization  on  a  similar  task.  Documentation  of  programs  and 
systems  must  be  adequate  to  enable  the  secondary  user  to  understand  the 
program  capabilities,  peculiarities,  and  limits  in  order  to  determine 
whether  the  program  meets  the  needs  stipulated.  Secondary  users  also  need 
good  documentation  to  understand  how  to  run  the  program  and  to  make  any 
necessary  modifications. 


In   ad  d  i  t 
pro j  ec  t 
requ  i  r  em 


canvasse 
need  for 
the  Stat 
so  f  twar e 
better  d 
technica 
include: 


ion  to  the  Software  Exchange  program,  GSA  has  recently  established  a 
to  obtain  documentation  Software  for  government-wide  use  under  a 
ents-type  contract.  As  a  follow-on  to  a  1974  GAO  Study,  wherein  GAO 
d  70-different  ADP  installations  and  concluded  that  there  exists  a 
better  documentation  in  the  Federal  government;  and  in  keeping  with 
ed  objectives  of  FIPS  PUB  38;  GSA  is  taking  an  active  role  in 
management.  Through  this  current  procurement,  we  plan  to  promote 
ocumentation  in  the  Federal  government  and  encourage  the  use  of  a 
lly     valid      automated     documentation     system.      The   expected  benefits 


more  emphasis  on  good  documentation,  with  the  result  that 
Federal   ADP   Managers   will   become   cognizant   of    this  need. 
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In  the  long  term,  this  emphasis  should 
ment  by  industry  of  more  efficient  and 
for   government  use 


result   in  developf- 
economical  software 


.   better  documentation  of  government   systems  which  will  aid 
in   application   program  development   and   program  maintenance 

.    achievement   of  volume   discounts    through    centralized  bulk 
procurement   and   elimination  of  procurement   costs   on  an 
agency-by-agency  basis. 

Why  Document? 

Because  it  is  essential  to  the  effective  development,  implementation, 
modification,    operation  and   utilization   of   any  system. 
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THE   PHILOSOPHY   OF  FIPS   PUB  38 


-  AN  INTRODUCTION 


James  Gillespie 
Chief   of   Naval   Operations  (OP-914D) 
Department   of   the  Navy 
Washington,   D.   C.  20350 

'I 

j    My  part    in   this   program   is   very   simple,    and   very  pleasurable.      First,    I  wish 
!    to  express   the  appreciation  of  FIPS  Task  Group   14  to  Mr.     Thornton     and  Mr. 
Puckorius   for   taking   the   time   to  participate   in   this  tyBposiuni. 

Second,  I  want  to  introduce  the  next  three  speakers,  who  will  describe  the 
different  aspects  of  the  philosophy  behind  FIPS  PUB  38.  Roy  Young  will 
describe  the  life  cycle  concept  and  the  document  types  which  occur  at  each 
stage  in  that  life  cycle.  Bob  Hegland  will  describe  the  flexibility  that 
f  each  agency  has,  both  in  developing  in-house  standards  or  guidelines,  and 
when  selecting  document  types  in  any  given  application.  Finally,  Tom 
Kurihara  will  provide  a  brief  description  of  the  content  guidelines  for  each 
of   the    ten  document  types. 

After  Tom's  presentation,  Mark  Silverman,  who  chaired  the  symposium  planning 
committee,  will  describe  the  rest  of  our  program.  It's  a  real  pleasure  for 
me  to  be  here  today.  I  hope  that  by  the  time  it's  over,  you'll  feel  the 
sane  way. 
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LIFE    CYCLE    CONCEPTS   AND   DOCUMENT  TYPES 


Roy  A.  Young 
U.S.    Department   of   Health,    Education,    &  Welfare 
330   Independence  Avenue,  SW 
Washington,   D.    C,  20201 

A  good  system  of  life  cycle  documentation  not  only  specifies  how  information 
is  to  be  recorded,  but  also  when  it  is  to  be  recorded.  It  has  long  been 
established  that  poor  or  inadequate  communication  between  personnel  is  a 
major  problem,  and  it  always  starts  at  the  initiation  phase  of  a  project, 
and    then   continues   until    the   system   is  terminated. 

If  documentation  is  done  concurrently  with  task  development,  the  completion 
of  each  task  is  signified  by  the  availability  of  the  finalized  documents.  A 
review  of  the  completed  documentation  during  development  and  after 
implementation  phases  provides  the  opportunity  for  assessing  progress,  and 
it   can   point   out   problem   areas   between   scheduled   and   actual  dates. 

When  newly  proposed  systems  are  to  interface  with  an  existing  system,  it  is 
vital  to  review  the  interaction  between  the  two  systems.  This  can  only  be 
achieved    if   the   previously   designed    system   is    adequately  documented. 

The  first  exhibit  (Exhibit  A)  is  easy  to  identify  with,  because 
documentation,  in  many  respects,  says  about  as  much  as  this  exhibit.  We  all 
have  reviewed  this  type  of  documentation  at  one  time  or  another  in  our 
careers.  We  hope  that  after  the  FIPS  PUB  38  Symposium  today,  we  can  all  go 
back  better  prepared,  so  we  don't  leave  those  who  come  in  contact  with  our 
documentation  frustrated  because  it  lacks  the  technical  explanations  and 
clarity    to   be  understood. 

Many  of  us,  as  managers  without  documentation  standards  and  policy 
guidelines,  have  been  confronted  with  the  individual  who  says,  "You  do  it 
your  way  and  I'll  do  it  mine."  (Exhibit  B)  Their  arguments  are  that  their 
documentation  is  adequate  to  do  their  job.  However,  we  all  know  that  for  a 
new  employee  given  a  new  project,  the  documentation  in  most  cases  is  not 
adequate.  It  is  easy  to  understand  the  programmer's  feelings  when  it  comes 
to  documentation  after  the  program  is  operational.  But  in  order  to  ensure 
the  continued  success  of  the  program  in  a  production  environment,  it  must  be 
capable  of  being  maintained.  Good  documentation  is  the  only  answer.  As  has 
been  pointed  out  by  earlier  speakers,  "It  pays  to  document."  Documentation 
is  the  result  of  hard  work  by  managers  and  their  staffs  (Exhibit  C).  How 
many  times  have  you  come  head-to-head  with  the  problem  of  documentation? 
The  manager  says,  "Hey!  Your  documentation  is  not  complete."  The  programmer 
planned  on  bringing  it  up  to  date,  but  has  several  excuses  as  to  why  he 
hasn't  documented  it.  As  a  manager,  we  have  a  responsibility  to  see  that 
documentation  is  kept  current  with  development  and  finalized  upon 
implementation. 

The  delicate  position  the  ADP  manager  is  in  when  it  comes  to  documentation 
is  pointed  out  in  Exhibit  D.  As  managers,  you  are  constantly  being  badgered 
by  your  staff  about  what  is  adequate  documentation.  If  you  allow  sub- 
standard documentation  to  occur,  eventually  the  user  or  your  boss  will  be 
all  over  you  like  a  tiger.  As  managers,  we  know  that  documentation 
standards  are  necessary  to  stay  out  of  trouble.  We  must  enforce 
documentation   standards    or   suffer   the  consequences. 

The  project  manager  (Exhibit  E)  has  the  ultimate  responsibility  for 
documentation.  He  is  the  one  who  must  sign  off  on  the  system  when  it  is 
ready  for  implementation.  He  must  determine  whether  the  documentation  is 
adequate,  because  he  must  satisfy  the  requirement  that  it  will  support 
programming  maintenance    functions   by   other  programmers. 
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When  we  talk  about  life  cycle  concepts,  we  mean  from  inception  of  a  new 
program  or  system  until  its  discontinuance.  The  definition  of  the 
documentation  elements  of  the  software  life  cycle  (Exhibit  F),  as  it 
pertains    to   FIPS   PUB   38   is    as  follows: 

PHASES .  While  terminology  used  to  describe  the  phases  is  arbitrary,  it 
provides  a  convenient  framework  within  which  the  development  of  software  may 
be  discussed. 


Initiation.  During  the  Initiation  Phase,  the  objectives  and  general 
definition  of  the  requirements  for  the  software  are  established. 
Feasibility  studies,  cost-benefit  analyses,  and  the  documentation  prepared 
within   this   phase   are   determined   by   agency   procedures   and  practices. 


Deve lopment .  During  the  Development  Phase,  the  requirements  for  the 
software  are  determined  and  the  software  is  then  defined,  specified, 
programmed,  and  tested.  Documentation  is  prepared  within  this  phase  to 
provide   an   adequate   record    of   the    technical    information  developed. 

Operat  ion .  During      the     Operation     Phase,      the      software      is  maintained, 

evaluated,    and   changed   as    additional   requirements    are  identified. 


STAGES.  While  the  terminology  used  to  describe  the  stages  is  arbitrary,  it 
provides  a  convenient  framework  within  which  the  development  of  the  ten 
document  types  may  be  discussed.  It  is  recognized  that  not  all  of  the 
document  types  are  required  to  document  software  in  every  case,  and  that  in 
some   cases,    the   various   document    types   may   need    to   be  combined. 


Definition.  During  the  definition  stage,  the  requirements  for  the  software 
and  documentation  are  determined.  The  Functional  Requirements  Document  and 
the    Data   Requirements   Document   may   be  prepared. 


Design.  During      the     design      stage,      the      design     alternatives,  specific 

requirements,  and  functions  to  be  performed  are  analyzed  and  a  design  is 
specified.  Documents  which  may  be  prepared  include  the  System/Subsystem 
Specification,  Program  Specifications,  Data  Base  Specification,  and  Test 
Plan. 


Programming .  During  the  programmin 
debugged.  Documents  which  may  be  prep 
Users     Manual,    Operations   Manual,  Prog 


g  stage,  the  software  is  coded  and 
ared  during  this  stage  include  the 
ram  Maintenance   Manual,    and   Test  Plan. 


Test.  During        the      test  stage, 

documentation  reviewed.  The  software 
terms  of  readiness  for  implementa 
prepared . 


the      software      is      tested      and  related 
and     documentation     are     evaluated  in 
tion.        The   Test   Analysis   Report  may  be 


DOCUMENT  TYPES.  The  purpose  of  each  of  the  ten  document  types  is  defined  in 
the    following  paragraphs. 

Functional  Requirement  s  Document .  The        purpose        of      the  Functional 

Requirements  Document  is  to  provide  a  basis  for  the  mutual  understanding 
between  users  and  designers  of  the  initial  definition  of  the  software, 
including    the   requirements,    operating   environment,    and   development  plan. 

Data  Requirements  Document.  The  purpose  of  the  Data  Requirements  Document 
IS  to  provide,  during  the  definition  stage  of  software  development,  a  data 
description   and    technical    information   about   data   collection  requirements. 

Sys tem/ Subsy s tem       Specification.  The      purpose      of      the      Sys tem/ Subsy s tern 

Specification  is  to  specify  for  analysts  and  programmers  the  requirements, 
operating  environment,  design  characteristics,  and  program  specifications 
(if   desired)    for   a   system  or  subsystem. 
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Program  Specification.  The  purpose  of  the  Program  Specification  is  tp 
specify  for  programmers  the  requirements,  operating  environment,  and  design 
characteristics   of   a   computer  program. 


Data  Base  Specification.  The  purpose 
specify  the  identification,  logica 
characteristics   of  a  particular  data  ba 

User's   Manual .      The   purpose   of   the  User 
the   functions   performed  by   the  software 
the     user     organization     can  determine 
use   it.      It   should   serve   as   a  reference 
data  and  parameters   and   for  interpretat 


of  the  Data  Base  Specification  is  to 
1  characteristics,  and  physical 
s  e  . 

's  Manual  is  to  describe  sufficiently 
in   non-ADP      terminology,      such  that 

its  applicability  and  when  and  how  to 
document   for     preparation     of  input 

ion   of  results. 


Operations  Manual.  The  purpose  of  the  Operations  Manual  is  to  provide 
computer  operating  personnel  with  a  description  of  the  software  and  of  the 
operational   environment   in  which   the   software   should  be  run. 


Program  Maintenance  Manual.  The  purpose  of  the  Program  Maintenance  Manual 
is  to  provide  the  maintenance  programmer  with  the  information  necessary  to 
understand  the  programs,  their  operating  environment,  and  their  maintenance 
procedures . 

Test  Plan.  The  purpose  of  the  Test  Plan  is  to  provide  a  plan  for  the 
testing  of  software;  detailed  specifications,  descriptions,  and  procedures 
for  all   tests;    and   test   data  reduction  and   evaluation  criteria. 


Test  Analysis  Report.  The  purpose 
document  the  test  analysis  results  and 
capabilities  and  deficiencies  for  rev 
a   statement   of   software   readiness  for 


of      the      Test     Analysis   Report    is  to 
findings,      present      the  demonstrated 
iew,    and   provide   a  basis   for  preparing 
implementation. 


12 
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I  believe   you  understand  what 
you  think   T  said  but  Tm  not 
sure  you   realize  that  what 
you  heard  is  not  what  I 


meant." 


EXHIBIT  A 
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Hey,  George!  This  is  supposed  to  be  a  team  effort. 


EXHIBIT 
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STAF  F 


M ANAGEHS 
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EXHIBIT  C 
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AN  ALYST 


PROCSRAMMER 


□  O  C  U  MEIMTS 


EXHIBIT  E 
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FLEXIBILITY   PROVISIONS   AND   DOCUMENT   TYPE  SELECTION 


Robert   R.    Hegland  * 
Naval    Command   Systems   Support  Activity 
(Code  70.3) 
Washington  Navy  Yard 
Washington,    D.    C.  20374 


[INTRODUCTION 

iMost     standards     and     guidelines     are     not     s e 1 f - imp lemen t ing .        To     be  most 

effective,  they  need  to  be  analyzed  by  a  central  office  to  establish  the 
policies     and     procedures     to     implement     them   in  a  particular  department  or 

agency.        The      central      office     must      establish     the     responsibilities  and 

implementation  procedures  that  will  make  the  standard  or  guideline  most 
useful   to   its  organization. 


Discussed  herein  are  those  policies  and  procedures  that  a  central  office 
should  consider  in  implementing  the  FIPS  Documentation  Guidelines.  The 
authors  of  the  documents  that  are  discussed  in  the  Documentation  Guidelines 
should  be  familiar  both  with  the  policies  and  procedures  that  are 
established  and  the  flexibility  provisions  contained  in  FIPS  PUB  38.  Anyone 
can  prepare  reams  of  documentation  but  it  takes  some  thought  and 
understanding   to   produce   useful  documentation. 

FLEXIBILITY  PROVISIONS 

1.      USING    SPECIFIED    SECTIONS   AND  PARAGRAPHS 

The  Guidelines  provide  ten  different  document  types,  each  of  which  has 
several  sections.  Each  section  has  numbered  and  titled  paragraphs  within 
it.  There  is  some  flexibility  in  using  these  paragraph  numbers  and  titles. 
Authors  are  encouraged  to  try  to  use  them  as  they  are  structured  in  the 
Guidelines,  since  a  great  deal  of  time  went  into  developing  them.  Also, 
much  of  the  Guidelines  is  based  on  a  documentation  system  that  has  been  used 
and  modified  over  a  number  of  years,  and  the  sequence  is  essentially  the 
same   as    is   used    in   that   documentation  system. 

o     There    is    the   provision  within    the   Guidelines    to   add  specific 
program  and    file   names    to   some   of    the  paragraphs. 

o      If   the   author   or    the    central   office   determines    that  additional 

paragraphs   or   sections    are   needed,    it    is    suggested    that  paragraphs 
be   added   at    the   end   of   a    section   and   sections   be   added   at    the  end 
of   the   document  type. 

o      Sections   and   paragraphs    can   also   be   deleted  when   they   are  not 

applicable    to   documenting   a   particular   system.      This   can  be  done 
in   two  ways:      by   simply   omitting   them,    or   by   including   a  short 
description   of   why   no   detailed    information   is    included.      An  example 
of   this    is   a   paragraph    in   the   Guideline    that   deals   with  security. 
If   the    system   is   not    classified,    there    is   no   need   to   include  a 
paragraph    that   explains    the   security   provisions    for  protecting 
the   system  and    its   data.      In   either    case,    the    integrity   of  the 
Section   and   Paragraph   numbers   and    titles    can  be  preserved. 


2.      AUDIENCES    AND  FUNCTIONS 

Another  provision  of  flexibility  that  needs  to  be  recognized  is  that  each  of 
the  document  types  is  designed  for  a  particular  audience  and  a  particular 
function.  This  concept  is  very  important  because  of  the  great  variety  of 
organizational  structures  that  we  find  in  data  processing  in  the  various 
government  departments.  A  given  computer  program  may  be  used  in  one 
organization  by  only  one  person,  who  acts  as  the  user,  computer  operator, 
and  maintenance  programmer.  In  another  organization,  there  may  be  three 
separate  people  serving  those  functions  for  that  program.  The  Guidelines  is 
intended      to     be      independent   of   organizational    structure,    so    that    it   can  be 
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used  in  both  situations.  Since  there  are  at  least  three  different  functions 
being  performed  in  each  situation,  the  three  different  documents  should  be 
prepared — one  each  addressing  the  function  of  the  user,  the  computer 
operator,  and  the  maintenance  programmer.  The  function  being  performed, 
rather  than  the  individual  looking  for  the  information,  determines  which 
document   is  referenced. 

3.  USE   OF  FORMS 

Another  provision  of  the  Guidelines  is  to  allow  (and  encourage)  the  use  of 
existing  forms  in  preparing  your  documentat  ion.  There  are  no  forms 
specified  in  the  Guidelines  as  being  mandatory  for  documenting  a  program, 
since  the  format  of  such  forms  changes  so  much  from  one  organization  to 
another,  and  since  there  are  elements  on  some  forms  that  change  depending  on 
the  particular  hardware  and  operating  system  you  have.  It  is  suggested, 
however,  that  your  forms  be  referenced  from  the  paragraphs  that  are  in  the 
Guidelines,  so  that  the  basic  structure  of  the  document  types  can  still  be 
used,   regardless   of   the   forms   that  you  may  be  using. 

4.  USE  OF   FLOWCHARTS   AND  LISTINGS 

Whether  or  not  to  include  flowcharts  and  listings  in  your  documentation  is 
another  area  where  there  should  be  a  policy  established.  Certainly,  the 
maintenance  programmer  should  have  access  to  these,  but  there  is  some 
question  as  to  whether  they  need  to  be  included  and  printed  in  a  document. 
It  usually  is  adequate  to  have  them  on  file,  rather  than  to  have  them 
printed   in  a   formal  document. 

5.  SUPPLEMENTING   THE   DOCUMENT  TYPES 

There  are  several  other  items,  in  addition  to  the  flowchart  and  listings, 
that  can  be  used  to  supplement  the  document  types.  These  are  useful  to 
remember  and  use,  since  the  documentation  needs  to  be  thought  of  in  a 
hierarchical  structure.  The  source  code  is  the  most  detailed  level  of 
documentation;  the  Program  Maintenance  Manual  is  the  next  most  detailed,  but 
should  not  be  thought  of  as  taking  the  place  of,  or  being  as  detailed  as, 
the  source  program  listing.  The  source  code  can  serve  this  function 
particularly  well  if  it  is  well  commented.  Another  supplement  can  be  the 
output  of  an  automated  flowchart  program.  It  would  seem  to  be  unnecessary 
to  have  a  printed  document  of  program  flowcharts  if  an  automated  flowchart 
package   is   available   to   printout   a    flowchart   whenever    it   may   be  needed. 

The  output  of  a  Data  Element  Library  also  can  be  used  to  reduce  the  amount 
of  typed,  formal  documentation.  This  output  could  either  be  included  in  the 
Document   or   referred    to   from   the  document. 

6.  OTHER   DOCUMENT  TYPES 

To  have  a  complete  documentation  system,  you  may  want  to  establish  some 
other  document  types,  such  as  a  technical  report  or  technical  note--that  can 
be   used   to   contain   supplements    studies,    or    catalogs,  etc. 

7 .  COMBINING   DOCUMENT  TYPES 

Some  document  types  can  be  combined,  in  some  instances.  Those  that  have 
most  frequently  been  combined  are:  Users  Manual,  Operations  Manual,  and 
Program  Maintenance  Manual,  to  form  a  Project  Manual;  several  Program 
Specifications,  to  form  a  Subsystem  Specification;  and  several  Subsystem 
Specifications,  to  form  a  System  Specification.  This  technique  may  be 
particularly  useful  on  small  projects,  but  must  be  used  with  some  care. 
After  all,  each  document  type  is  intended  for  a  different  audience  and  may, 
therefore,  have  a  different  distribution.  Additionally,  the  different 
documents  will  almost  surely  be  completed  at  different  times,  so  a  combined 
document   cannot   be   published   until    the    last   "piece"    is  finished. 

DOCUMENT   TYPE  SELECTION 

In  deciding  what  document  types  should  be  produced  for  a  particular  project, 
there  are   two     different     approaches     presented     in     the     Guidelines.  Your 
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organization  may  want  to  adopt  one  or  the  other,  it  may  want  to  change  some 
of  the  factors  in  one  before  adopting  it,  or  it  may  leave  that  decision  to 
the  project  leader. 

1.  COST/USAGE   THRESHOLD  CRITERIA 

Figure  2  in  FIPS  PUB  38  presents  a  technique  based  on  the  anticipated  cost 
or  use  of  the  project  to  determine  the  document  types  that  need  to  be 
produced  . 

2.  PROJECT  COMPLEXITY 

Figure  4  in  FIPS  PUB  38  shows  a  chart  with  twelve  "complexity  factors",  each 
of  which  can  be  assigned  a  weight  or  "value"  between  1  and  5.  When  the 
values  are  added  together,  the  overall  complexity  total  can  be  applied  to 
Figure  3  in  the  Guidelines,  to  determine  what  document  types  are  needed  for 
a  project  of   that  complexity. 

There  are  some  overriding  considerations  that  should  be  analyzed  in  deciding 
which  document  types  will  be  produced,  such  as  whether  a  contractor  will  be 
involved  in  the  project,  whether  you  are  automating  a  previously  manual 
function,    and  whether  you  will   be  working  with  an   integrated  data  base. 

3.  MANAGEMENT  CONSIDERATIONS 

A.  DOCUMENTATION  PLAN 

One  "of  the  first  things  that  should  be  done  during  project  development  is  to 
prepare  a  Documentation  Plan  to  determine  what  documents  will  be  produced 
during   the  project.      Other   items   that   should   be   considered   in  this  plan  are: 

o     Approximate   size    (or   range)   of   each  document. 

o     Portions   of  each  document   that   are  and   are  not  needed. 

o     Level   of   detail   of   each  document. 

o     Dates   when  portions   of    the   documents   will   be   available  for 
management  review. 

B.  REDUNDANCY 

In  applying  the  various  flexibility  criteria,  the  question  of  redundancy 
needs  to  be  clearly  understood  by  the  central  office  and  the  authors  of  the 
documents.  There  are  three  kinds  of  redundancy  that  have  been  included 
intentionally   in   the  document  types: 

o     Stand   Alone.      The   first   section  of   each  document  contains 
information  on   the   background   of   the   overall   project,  to 
set   a    frame   of   reference    for    the  reader. 

o     Apparent.      Many   documents   appear   to   call    for   the  same 

information.      The   information   that   is   provided,  however, 

may  be  different,   because   it   is   intended   for  different  audiences, 

o     Evolutionary.      There   also   appears    to   be   some   redundancy  between 
document    types;    it   provides   programmers    the   opportunity  to 
document    changes    that   have    taken   place    since   prior  documen- 


tation was  produced 


CONCLUSION 


This  has  been  a  brief  summary  of  the  different  flexibility  provisions  in  the 
Documentation  Guidelines.  There  are  many  factors  that  need  to  be  understood 
before  the  maximum  benefit  can  be  derived  from  it.  The  Guidelines  is  not 
"s e 1 f -imp lemen t ing" ,  and  must  have  the  involvement  of,  and  support  from,  a 
central   office   if   it    is    to   be   used  effectively. 


*     The   views    expressed   herein   are   those   of    the   author   and   do   not  necessarily 
represent    policy   of    the   Department   of    the   Navy   or   of   any   naval  activity. 
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CONTENT  GUIDELINES 


Thomas  M.  Kurihara 
Technical   Resources  Staff 
Data   Systems  Division 
Agricultural   Stabilization  and   Conservation  Service 
U.    S.    Department   of  Agriculture 
P.    0.    Box  2415 
Washington,   D.    C.  20013 


PURPOSE 


The,  purpose  of  my  portion  of  the  Philosophy  of  FIPS  PUB  38  is  to  describe 
briefly  Part  3,  the  Content  Guidelines.  The  Content  Guidelines  in  FIPS  PUB 
38  serves  to  provide  managers  of  development  projects  with  a  guide  to  follow 
in  prescribing  and  reviewing  project  documentation,  and  writers  of  documents 
with   content  guidelines. 

Part  3  of  FIPS  PUB  38  outlines  and  describes  the  content  guidelines  for  ten 
document  types  that  could  be  prepared  during  the  software  development  phase. 
Before  addressing  the  content  guidelines  for  each  of  the  document  type,  we 
must  keep  in  mind  the  purpose  of  documentation.  These  content  guidelines 
were  prepared  to  provide  a  vehicle  for  communication  between  the  user  and 
development  groups.  Each  document  type  is  intended  to  be  written  for  and 
used  by,    a  specified  audience. 


AUDIENCES 


The  audience  (or  intended  reader)  may  be  an  individual  or  a  group  of 
individuals.  In  the  development  of  automated  data  systems  and  computer 
programs,  there  are,  in  general,  two  audiences:  the  user  group  and  the 
development  group.  The  user  group  provides  data  inputs,  uses  the  outputs, 
states  the  requirements  for  the  development  effort,  and  assumes 
responsibility  for  acceptance  and  use  of  the  system.  The  development  group 
performs   the   design,   programming,    and   test  functions. 

We  recognize  that  your  work  environment  and  individual  manager's 
requirements  will  vary.  Regardless,  it  must  be  emphasized  that  when  each 
document  type  is  written,  the  audience,  and  its  function,  should  be 
identified  and  understood.  Consideration  should  be  given  to  audience 
knowledge     and   experience,   writing   style,    terminology,   and   anount  of  detail. 

Elaborating  on  Bob's  description  of  functions,  let's  look  at  the  specific 
"management"  audiences.  I  will  call  the  first  "Approval  Management".  Their 
function  is  to  make  decisions  concerning  the  project  based  on  its 
contribution   to  overall   organization  objectives. 

"Development  Management"  is  interested  in  the  amount  of  change  that  must  be 
anticipated;  the  completeness  of  user  requirements;  complexity;  mode  of 
operation;  available  resources;  and  system  life.  Their  function  is  to 
develop  a  set  of  technical  specifications  for  the  final  product,  from  which 
program  code  is  prepared  and  tested.  These  specifications  are  translated 
from  functional  descriptions   stating  user  requirements. 

"User  Management"  is  concerned  with  improved  efficiency  and  effectiveness; 
better  information  for  decisions;  training;  and  internal  procedures.  Their 
function  is  to  review  the  development  of  the  system,  use  the  developed 
systems,  identify  performance  and  acceptance  criteria,  and  train  user 
personnel . 

The  developers  are  concerned  with  product  performance,  correct  and  complete 
specifications,   and   completing   the  project  on  time.     The  users,   on  the  other 
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hand,  are  concerned  with  furnishing  data,  changing  procedures  to  fit  the  new 
system,  and  understanding  how  the  new  system  will  affect  their  everyday 
f unct  ions . 

Therefore,  with  an  understanding  of  who  the  audiences  are,  the  writers  of 
documentation  should  be  guided  by  the  content  guidelines  contained  in  FTPS 
PUB  38.  The  following  comments  are  intended  to  provide  a  capsule  summary  of 
each  of  the  ten  document  types, 

DOCUMENT  TYPES 
Functional  Description 

o     Describes   the  development   group's  understanding  of   the  user  group's 

requirements   for   an  operational  capability, 
o     Written   in   "user   language",   minimizing   technical   terminology  about 

ADP  hardware, 

o     Contains   an  analysis   of  methods,    impacts,    cost,   requirements,  and 

operating  environment, 
o     Submitted   to   the   user   for   concurrence,   and   to  user  management  for 

approval,   prior   to  preparing   detailed   system  specifications, 
o     Basic   reference  document   for   determining   the   impact   of   any  change 

to   the   scope  of   the  project  made   prior   to   user  acceptance, 
o     Contains   a   development   plan   identifying  milestones   and  participation 

by  other  organizations. 

Data  Requirements  Document 

o     Describes   the  development   group's  requirements   for   data,   and  the 

user  group's   data   collection  effort   to  establish  and  maintain  system 
files  . 

o     Written   in  user  terminology. 

o     Contains  descriptions   of   input   data,   procedures   and   constraints  in 

data  handling,    expected   outputs,   and   specifications   of  data  elements, 

o     Submitted   for  user   concurrence;    serves  as   a   source  of  data 
specifications   for   the   development  group. 

o     Basic   reference   document   for   description  of  data. 

System/Subsystem  Specification 

o     Describes   the   system  structure,    function,   and   flow  to  analysts  and 

programmers    in   the   development   group,    at   a    level   of   detail  beyond 

the   functional  description, 
o     Written  as   a   technical   document,    in  enough  detail   to  carry  out 

program  design   and  coding, 
o     Contains  performance  requirements   and   design  logic   for  the 

system/ subsystem, 
o     Submitted   to  development  management   for  review  and  approval, 
o     Defines   the   types   of   interfaces  with  other   sy s t ems / subsy s terns  and 

the  operating  environment, 
o     Basic   reference   for   assessment   of   impact  of   design   changes  approved 

by   the  user,   within  the   scope  of   the  described  system. 

Program  Specification 

o     Describes   the  program  requirements   to   analysts   and  programmers  in 

the   development  stage, 
o     Written  as   a   technical   document,    in  enough  detail   beyond   the  system 

specifications   to   describe   adequately  the   component  functions, 

outputs   and   performance   to  permit  program  coding  and  testing, 
o     Contains  performance   requirements,    instructions   for   operations,  data 

structures,    and   program  logic, 
o     Submitted   to   technical  development  management   for  review  and  approval. 
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Data  Base  Specification 


o     Describes   the   attributes  of  data  bases,    and   data   elements  contained 
therein,   when   several   groups   are   involved   in  maintaining  and  using 
the   same  data  base. 

o     Written   in  data  base   terminology,    for  use   by  programmers   and  by  data 
base  managers. 

o     Contains   detailed   information  to   permit   coding,   data  base  generation, 
and  maintenance. 

o     When  a  data  base  management   system   is   used,    this   document  may 

supplement   the   DBMS  documentation, 
o     Alternative   formats   are   described;   however,    to   achieve  consistency 

in  presentation,    the   following  practices   should   accompany  the  use  of 

this   document  type: 

-  Establish   the   order   of  contents;    for   example,    as   given  in  the 
content  guidelines. 

-  Follow  each   item  description  with   the   formatted  arrangement 
of  data . 

-  Descriptions   and  naming   conventions   should  be   consistent  with 
your  data  base  administration  policies   and  conventions. 

User's  Manua 1 

o     Describes  how  the  user  group  will   use   the  automated  data   systems  and 

computer  programs   prepared   by   the   development  group, 
o     Written   in  user   format,   with  user  terminology. 

o  Contains  instructions  and  procedures  for  data  entry,  equipment 
operations,  interactive  queries,  and  sample  outputs.  Sections 
1  and  2  are  directed  toward  user  management.  Sections  3  and  4 
are  directed   to   the  users. 

o     Submitted   to  user  management   and   staff   for  approval,    and  may  be 
used  as   basis   for  training. 

o     Basic   reference  document   for  determination  of   the   impact  of  changes 
on  procedures,   and   impact   of  computer   system  changes   on  procedures. 
Has   the   equivalent   level   of  detail   for  users   as   the  Program 
Specification  does    for   the   development  group. 

Operations  Manual 

o     Describes  how  the   computer  operations   personnel  will   initiate,  run, 

and   complete   processing   of   the  job. 
o     Written   in   operations    terminology,    and   usually   follows   a  step-by- 

step-scenerio. 

o     Contains   instructions   and   procedures   for   routine   operations   and  for 

recovery   (i.e.,   non-routine  operations), 
o     Contains   instructions   and  procedures   for  remote   terminal  operations, 

if   they   are   required    for   data   entry  or   remote   batch  operations. 

Program  Maintenance  Manual 


o     Describes    the   accepted,    operational    computer   programs    for  the 
maintenance   programmers,    who   are   responsible    for   making  changes 
to   those  programs.     The   design  approach,   program  logic,  related 
data,    and   operating   characteristics   are  described. 

o      Contains   diagrams   and    listings   of   source    code    for   the  operational 
version  of  programs,   and  narrative   explanations   of  interfaces, 
parameters,    codes,    and  messages. 

o     Describes    interface   and   dependencies   with   the   operating  system. 

o     Provides   a  history   of   changes  within   the    scope   of   the  original 
requirements, 

o     Refers   or   contains    test    information   and    test  data. 
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Test  Plan 


o     Describes  the  test  plan,    testing  procedures,   test  criteria,  and 
evaluation  criteria. 

o     Written  as   a  non-technical   document   for   users   and   staff  personnel 
conducting  tests;    and   in  appropriate   technical   terminology  for 
analysts,   programmers,   and   operations  personnel, 

o  Contains  test  specifications  and  details  concerning  the  step-by- 
step  testing  procedures, 

o  Testing  procedures  should  cover  all  interfaces  among  system/sub- 
systems, programs,  and  data  bases;  and  describe  the  relationship 
among   test   programs  or  functions, 

o     Test  methodology,    data,    and   results   should   be  retained   for  verifi- 
cation of  the  tests. 

Test   Analysis  Report 

o     Describes   the  results  of   the  test. 

o     Written   for  management,    describing   the   test  results   for  management 
decision  regarding   the   acceptability  of   the  product.      Results  should 
be   compared   to   the   operational   requirement   and  performance 
capabilities   to   assure   that   all   design  changes  have   been  incorporated 

o     Describes   deficiencies   and   corrective  actions  necessary   for  accept- 
ance  or,    if   the   deficiency   is   not   corrected,    the   impact   on  the  system 

o     Contains   explicit   user  acceptance   in  his   statement   that   the   system  is 
ready   for  operation, 

o     List   of   improvements   which   can  be  made   in  design  or   operation  of  the 
system  as   determined   during   the   test  period. 

CONCLUSION 

With  an  understanding  of  the  audience  and  content  guidelines,  the  writer  of 
documentation  can  now  turn  to  the  preparation  of  project  documents  using  his 
respective  Agency  style,    forms,    and   format  conventions. 

FIPS  PUB  38  has,  as  a  Federal  guideline,  a  high  degree  of  flexibility  in  its 
application  and  implementation.  Any  and  all  feedback  to  TG14  concerning 
your  experiences  in  using  it  will  provide  us  with  the  information  needed  to 
make   the   changes   to   better   suit   Federal   ADP  managers. 
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DESCRIPTION   OF   AFTERNOON  SESSIONS 


Mark  Silverman 
Technical   Staff  Assistant 
U,    S.   Geological  Survey 
National   Center,   Mail   Stop  801 
Reston,    Virginia  22092 

For  the  remainder  of  the  symposium  there  will  be  three  parallel  sessions,  as 
f ol lows : 

Session  A,  which  is  slanted  towards  executives,  user  managers,  and  project 
managers,  will  be  moderated  by  Robert  V.  Head,  Mr.  Head  is  the  Assistant 
Director  of  the  Office  of  Automated  Data  Systems  at  the  U.S.  Department  of 
Agr,iculture .  He  has  been  with  the  Department  since  1971,  and  has  held 
several  key  positions  as  a  computer  executive.  Before  entering  government 
service,  Mr.  Head  worked  for  several  years  as  an  information  systems 
consultant.  From  1963  to  1965,  he  served  as  Vice  President  in  charge  of 
systems  planning  for  Security  Pacific  National  Bank.  He  was  associated  with 
International  Business  Machines  from  1959  to  1963,  first  as  a  senior  systems 
engineer  and  later  on  the  staff  of  the  IBM  Systems  Research  Institute. 
Earlier,  he  worked  as  a  manager  and  programmer  for  General  Electric  and 
UNIVAC.  Mr.  Head  holds  the  Certificate  in  Data  Processing  of  the  Data 
Processing  Management  Association,  has  twice  served  as  a  National  Lecturer 
of  the  Association  for  Computing  Machinery,  and  is  a  past  President  of  the 
Society  for  Management  Information  Systems,  He  served  as  a  Contributing 
Editor  of  Pat  ama t  ion  magazine  from  1965  to  1971,  He  is  the  author  of  three 
books  and  more  than  40  papers  in  the  field  of  business  systems.  He  received 
a  B.A.  in  Government  from  George  Washington  University,  where  he  was  a 
member   of   Phi   Beta  Kappa, 

Session  B  should  be  of  interest  to  ADP  Systems,  Operations  and  Programmer 
Personnel,  and  will  be  chaired  by  Thomas  P.  Giammo.  Mr,  Giammo  is  the 
Director,  Division  of  Statistical  Processing,  at  the  Social  Security 
Administration.  In  this  capacity  he  is  responsible  for  the  computer 
processing  of  all  internal  management,  administrative,  and  statistical 
research  activities  of  the  Social  Security  Administration.  Before  joining 
the  Social  Security  Administration,  Mr.  Giammo  was  Deputy  Director,  Data 
Management  Center,  at  the  Department  of  Health,  Education  and  Welfare. 
Prior  to  entering  government  service,  he  was  Director  of  the  Washington 
Computer  Center  of  TRW  Systems,  and  he  also  was  associated  with  Gulton 
Systems  Research  Group,  Inc.  as  Vice  President.  Mr,  Giammo  received  a  B,S. 
in  Math    from  R,P,I.    and   a  M.A,    in  Math    from  U.C.L,A, 

Session  C ,  which  is  aimed  at  those  of  you  who  are  interested  in  Standards, 
Training,  Policy,  and  Audit  will  be  chaired  by  Harris  G.  Reiche,  Mr,  Reiche 
is  Director  of  the  Office  of  ADP  and  Telecommunications  Management, 
Department  of  the  Interior,  He  is  responsible  for  policies,  planning,  and 
reviews  pertaining  to  the  acquisition  and  management  of  automatic  data 
processing  and  telecommunication  resources  throughout  the  Department  of  the 
Interior.  During      1974-75,      he      served     as      Chairman     of      the  Government 

Interagency  Committee  for  Automatic  Data  Processing.  He  came  to  the 
Department  of  the  Interior  in  September  1973,  with  the  responsibility  for 
establishing  a  Department  ADP  management  organization.  Previously,  Mr. 
Reiche  had  served  22  years  with  the  Department  of  Defense — since  1957, 
within  the  data  processing  field,  where  he  served  primarily  in  ADP  planning 
and  policy  roles  with  the  Department  of  the  Air  Force.  His  last  assignment 
prior  to  joining  Interior  was  as  Director  of  Policy,  Technology  and 
Standards,  in  the  Office  of  the  Secretary  of  Defense.  During  this  period, 
he  also  served  on  the  Information  System  Technical  Advisory  Board  of  the 
American  National  Standards  Institute.  Mr,  Reiche  received  a  B,S.  in 
Business  Administration  from  the  University  of  California,  Berkeley  and  an 
M.S.    in   Information   Systemsl-rom  George  Washington  University. 
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USDA  APPLICATION  MANAGEMENT 

Robert   V.  Head 
Office   of  Automated   Data  Systems 
U.    S.    Department   of  Agriculture 
Washington,    D.    C.  20250 


Let  me  begin  by  providing  a  brief  profile  of  the  Department  of  Agriculture's 
ADP  operations.  In  terms  of  size,  we  fall  between  the  two  other  members  of 
this  panel.  We  are  a  lot  smaller  than  DoD,  and  somewhat  larger  than  HUD; 
with  an  ADP  budget  of  about  $65  million.  Approximately  two-thirds  of  our 
ADP  funds  are  devoted  to  application  development  and  maintenance,  so  the 
subject  of  documentation  standards  has  obvious  importance  for  a  manager  who 
is   concerned  with  where   the  dollars   are  going. 

In  general,  our  environment  can  be  described  as  one  of  centralized  data 
processing  and  decentralized  application  development.  We  operate,  in  the 
Office  of  Automated  Data  Systems,  four  computer  centers,  and  these  centers 
serve  25  using  agencies  and  staff  offices.  Thus,  we  have  a  somewhat 
centralized  operations  set-up  and  a  highly  decentralized  user  organization 
in  which   application   development  work   is    taking  place. 

The  main  vehicles  for  disseminating  ADP  policy  and  standards  information 
within  USDA  are  the  Departmental  Information  Processing  Standards  manual  and 
Title  11  of  the  Administrative  Regulations  of  the  Department.  We  have 
sought    to   introduce   FIPS   PUB    38  material    into   both   of   these  documents. 

We  have  adapted  the  system  development  life  cycle  found  in  FIPS  PUB  38,  and 
published  it  in  our  Departmental  Information  Processing  Standards  manual. 
We  are  concentrating  on  documentation  during  the  initiation  phase  of  a 
project.  The  reason  for  this,  thinking  in  terms  of  management  control  over 
ADP  resources,  is  that  this  is  the  point  at  which  both  executive  managers 
and  project  managers  should  see  some  documen t a t i on--be f ore  the  project  has 
gained  approval  or  moved  into  the  development  phase.  ADP  resources  are 
scarce,  and  we  have  projects  competing  for  these  resources.  We  would  like 
our  managers  to  look  at  each  project  proposal  critically  while  it  is  in  the 
initiation  phase,  or  at  least  before  it  has  gone  beyond  the  definition  stage 
of  the  development  phase.  So  we've  identified  documentation  requirements 
that  apply  both  to  all  USDA  agencies  and  central  staff  offices.  We  have 
tied  documentation  into  a  managerial  approval  process.  We  believe  that  by 
emphasizing  the  initiation  phase  and  emphasizing  the  role  of  management 
approval  based  on  FIPS  PUB  38  type  of  documentation,  we  are  orienting  our 
work   towards   managerial  interests. 

In  the  Agricultural  Regulations,  we  require  that  each  agency  of  the 
Department  with  a  significant  ADP  budget  set  up  an  Application  Review  Board. 
We  define  significant  as  a  million  dollars  in  budget,  or  more.  Agency  ADP 
budgets  within  USDA  range  anywhere  from  $5,000  a  year  to  more  than  $15 
million  per  year.  A  dozen  or  so  are  spending  a  significant  amount  of 
resources   on  ADP,    and   have   established   Applications   Review  Boards. 

The  chairman  of  each  board  is  at  a  top  management  level  within  the  agency. 
We  suggest  the  level  of  Deputy  Administrator  for  Management.  There  also 
should  be  membership  on  the  board  by  people  who  represent  the  program  areas 
of    the   agency--the    important   mission   areas   of   the  agency. 

As  we  structure  our  boards,  we  do  not  have  the  information  systems  director 
of  the  agency  serving  on  the  Board.  We  view  the  Board  as  engendering  a  sort 
of  adversary  relationship  between  the  systems  development  staff  and  the  top 
management  of  an  agency.  The  Board  is  there  to  look  critically  at 
application  proposals,    to   challenge   them,    to   try   to  make  resource  allocation 
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decisions  based  on  top  management's  viewpoint,  and  not  on  the  viewpoints  of 
the   technicians   in   the  organization. 

The  Application  Review  Boards  are  charged  with  reviewing  planned 
applications  during  the  initiation  phase,  again  tied  into  the  FTPS  PUB  38 
life  cycle.  A  major  application  must  go  before  the  Board  for  review  while 
it  is  in  the  initiation  phase.  A  major  application,  for  purposes  of  Board 
review,  is  one  on  which  $50,00.0  is  expected  to  be  spent  during  the  life  of 
that  application. 

The  Board  must  review  all  Automated  Decision  Making  Applications  (ADMA's), 
regardless  of  size.  Similarly,  the  Board  must  review  any  planned 
application,  regardless  of  size,  that  processes  personal  information,  as 
defined   by   the   Privacy   Act   of  1974. 

Among   the   responsibilities   that   the   boards   are   charged  with  are: 

1.  To  review  cost-benefit   analyses   of  applications. 

2.  To  assign  priorities   to   applications   in  accordance  with 
their   cost-effectiveness    and    their   importance    in  meeting 
the  program  requirements   of   that  agency. 

3.  To  review  the   implementation  schedules   of  proposed  projects 
in   terms   of   the   agency's   mission  requirements. 

There  is  a  form  that  is  intended  to  help  in  the  review  process.  The 
"Request  for  Agency  Planning  Data"  form  is  geared  to  the  philosophy  and 
terminology  of  FIPS  PUB  38.  It  has^  two  major  parts.  The  top  part  covers 
the  application  initiation  phase,  the  bottom  part  the  application 
development  phase.  This  means  that  in  the  life  cycle  of  a  project,  two 
forms  must  be  completed  and  submitted  for  review  as  the  project  moves 
through  <3ie   initiation  phase   into   the   application  development  phase. 

There  is  a  date  to  be  provided,  which  represents  the  time  at  which 
management  approval  has  been  secured  for  a  project.  There  is  another  date 
to  be  filled  in  which  indicates  when  a  cost  benefit  analysis  has  been 
completed  for  the  project.  There  are  also  provisions  for  estimating 
schedule   dates   and   summarizing   cost   estimates   for   the  project. 

During  the  initiation  phase,  we  ask  for  a  rather  gross  indication  of  what 
the  dollars  estimated  to  go  into  the  project  will  be.  If  the  project  leaves 
the  initiation  phase  and  proceeds  into  the  development  phase,  there  is  some 
additional  cost  information  that  must  be  provided.  Within  the  development 
phase,  we  ask  for  a  breakout  of  schedule  dates  and  estimated  costs  for  each 
of  the  steps  within  that  phase.  At  this  point,  those  most  concerned  with 
the  project  should  be  able  to  do  a  more  precise  job  of  estimating  their 
costs.  The  important  thing  to  emphasize  here  is  that  through  our  procedures 
and  through  our  high  level  documentation,  we  have  adapted  the  life  cycle 
concept  of  FIPS  PUB  38  and  some  of  its  substantive  information  content  to 
our  management   approval  process. 

I  don't  want  to  mislead  anyone  by  indicating  that  the  system  is  fully 
installed  and  operating  smoothly.  It  is  very  new  in  several  respects. 
There  are  pieces  that  are  missing.  For  example,  we  still  don't  have 
satisfactory  guidelines  for  doing  cost  benefit  analyses.  We  look  to  NBS  for 
further     progress    in   guidelines    that   will   aid   in  managerial   decision  making. 
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DOCUMENTATION  STANDARDS 


-   A  MANAGEMENT  VIEW 


Eugene  B. 
Data    Systems    &  Appl 
Agricultural  Res 
National  Agricultural 
Beltsville , 


Smith 
ication  Division 
earch  Service 

Library   -  Room  003 

MD  20705 


Variations  in  data  processing  activit 
out  the  need  for  flexibility  in  the  e 
documentation  standards.  This  paper 
the  real  and  perceived  value  of  d 
integrating   certain   elements   of    the  sta 


ies  and  documentation  practices  point 
stablishment  and  implementation  of 
will  briefly  explore  the  thesis  that 
ocumentation  can  be  increased  by 
ndards    into   the  management  process. 


Documentation  Style  -  One  may  disagree  with  specific  terminology  presented 
in  FIPS  PUB  38,  but  it  does  represent  the  traditional  approach  to 
documentation.  Since  the  concept  is  presented  as  a  set  of  guidelines,  an 
agency  has  considerable  flexibility  in  implementing  standards.  Compliance 
will  impose  a  certain  amount  of  formality,  which  is  desirable.  In  addition 
to  improved  applications  systems,  a  significant  benefit  from  compliance 
should  be  improved  management  procedures  in  the  areas  of  control, 
cost/benefit   analysis,    and  planning. 


Last  Fall  I  took  my  graduate  students  to  visit  two  major  oil-related 
companies  in  Houston.  During  the  course  of  the  visit,  we  questioned  each  of 
these  large  companies  about  the  level  of  documentation  required  in  the 
development   of   new  applications. 


The  first  company's  documentation  practices  were  relatively  formal,  and  by 
way  of  implementation  they  routinely  utilized  a  standards  and  procedures 
manual  which  was  about  400  pages  long.  It  was  comforting  to  note  that  the 
traditional  textbook  approach  was  actually  being  followed  out  in  the  "real" 
world  . 


The  second  company's  approach  to  documentation  standards  and  procedures  was 
completely  informal.  They  had  no  published  standards,  and  required  very 
little  documentation  other  than  a  series  of  working  programs.  Their 
approach  was  that  there  would  always  be  more  than  one  person  available  who 
was  intimately  familiar  with  each  system.  When  questioned  about  the  need 
for  a  more  structured  approach,  the  director  indicated  that  they  were 
results-oriented   and   could    not    afford    the    luxury   of  more  documentation. 

The  data  processing  operations  of  both  companies  have  been  successful  for 
many  years.  The  different  approaches  represent  different  management  styles, 
and  the  success  of  the  informal  approach  may,  in  part,  be  attributed  to  a 
certain   amount   of  luck. 


This  contrast  in  approaches  tends  to  highlight  the  question  of  perceived 
cost  versus  benefit.  What  priority  do  we  place  on  documentation  in  terms  of 
a  completed  system?  Can  we  afford  to  provide  adequate  documentation?  Can 
we   afford   not  to? 


If  we  were  to  conduct  a  documentation  audit  of  a  number  of  DP  operations,  I 
am  convinced  that  we  would  find  a  very  small  percentage  actually  following 
adequate  documentation  practices.  Why  should  this  condition  exist?  Would 
we  purchase  a  software  package,  which  we  had  to  maintain,  that  was  seriously 
deficient    in   documentation?      Probably  not. 

Unfortunately,  too  often,  we  do  not  consider  documentation  to  be  an 
essential  element  of  internally  developed  systems.  We  want  to  get  the 
system  working,  and  don't  really  have  time  for  documentation.  We  fail  to 
recognize    that   good   documentation   can   significantly      impact      the     value  and 
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usefulness     of     a     system.        Documentation     is  more 
statements   in  a  program.      It   should   be  viewed  as  an 
system,    and   a  useful  management  tool. 


than  just 
integral 


a  few 
part 


comment 
of  the 


QUANTITY 

APPLICATION   SOFTWARE    DEVELOPMENT   -   PRODUCTION   PER   UNIT   OF  RESOURCE 


There  seems  to  be  a  conflict  between  quality  and  quantity,  as  indicated  by 
Curve  1  on  the  above  Figure.  In  considering  the  production  of  a  DP 
organization,  it  is  possible  that,  by  the  routine  use  of  good  documentation 
standards,  the  level  of  quality  for  a  given  quantity  of  work  could  be 
increased,    as    shown   by     Curves    2   or  3. 

Documentation  Survey  -  While  conducting  an  internal  study  to  assist  in 
developing  documentation  standards  for  the  Agricultural  Research  Service,  it 
was  decided  that  there  might  be  some  value  in  a  survey  of  some  20  sister 
agencies.  The  survey  was  intended  to  provide  a  vehicle  for  determining  how 
documentation  was  being  handled  by  other  agencies,  and  to  allow  the 
collection  of  documentation  material  which  might  be  of  assistance  in  our 
endeavor . 

The  size  of  the  data  processing  function  varied  widely  from  agency  to 
agency.  Agency  budgeted  expenditures  ranged  from  about  $24,000  to  over 
$16,000,000.  Numbers  of  data  processing  related  employees,  ranged  from  1  to 
over  400.  Project  size  ranged  from  less  than  one  man  day  to  several  man 
years   of  effort. 

While  it  was  possible,  during  a  brief  visit,  to  get  some  idea  of  the  nature 
of  the  standards  available,  it  was  not  possible  to  observe  how  well  the 
standards  were  being  utilized.  In  terms  of  existing  standards,  it  is  safe 
to  say  that  they  varied  from  non-existent  to  very  good.  Generally,  the 
agencies   with    few  DP   professionals   needed    the  most    improvement    in  standards. 

Some  agencies  receive  DP  support  from  other  agencies,  and  have  virtually  no 
standards  of  their  own.  Essentially,  they  accept  the  documentation 
provided.  Some  agencies  "contract  out"  major  projects  to  commercial  firms. 
In  these,  the  documentation  is  included  as  part  of  the  contract,  and  the 
results    seem   to   be   generally  good. 

The  agencies  with  large  DP  professional  staffs  seemed  to  be  more  concerned 
with  the  status  of  documentation  standards,  and  with  control  over  their  use. 
There  were  a  couple  of  notable  exceptions,  where  relatively  small  staffs 
placed  a  special  emphasis  on  documentation.  Two  agencies  had  recently 
initiated  major  efforts  to  develop  new  documentation  standards  in  compliance 
with   the   FIPS   and   DIPS    (our   departmental    guidelines)  publications. 

Since  FIPS  PUB  38  recognizes  four  levels  of  documentation,  based  on  usage 
and  cost  factors,  it  is  flexible  enough  to  accommodate  the  range  of 
variation      found      in     the      survey.        In     general,      there      seemed      to     be  no 
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disagreement  about  the  need  for  documentation,  nor  was  there  any  quarrel 
with   the   guidelines   embodied   within   the   FIPS   and   DIPS  publications. 


Improving  the  Perceived  Value  of  Documentation  -  It  should  be  possible  to 
integrate  mu  c  h  of  the  minimal  (or  level  O  documentat  ion  requirements  into 
the  internal  management  control  system.  Much  of  the  information  desired  for 
documentation,  is  also  needed  for  management.  If  standard  documentation 
practices  are  not  adequate,  one  may  question  the  adequacy  of  management 
prac  t  ices . 

Consider  the  types  of  information  generated  throughout  the  Software  Life 
Cycle,  The  information  assembled  in  the  initiation  phase  corresponds  to  the 
types  of  information  required  to  plan,  organize,  and  manage  the  effort  of  a 
DP  organization. 

It  should  be  possible  to  design  a  Service  Request  Form  that  would  serve  both 
the  documentation  and  management  processes.  Such  a  form  could  include  the 
following   types   of  data: 


DESCRIPTIVE   PROJECT  DATA 
TITLE 
ABSTRACT 
CONTACT 
DATE  REQUIRED 
CONSIDERATIONS    -  Privacy 

-  Security 

-  SPECIAL 

TYPE   OF  REQUEST 


PROJECT   CONTROL  DATA 
PROJECT  NUMBER 

RESOURCES   REQUIRED   -    SALARY  COSTS 

-  COMPUTER  COSTS 

-  OTHER  COSTS 

ASSIGNMENT  DATA 
TARGET  DATES 


The  minimal  documentation  level  would  also  include  other  material,  depending 
on  the  nature  of  the  project.  Higher  documentation  levels  would  include 
additional  elements,  as  described  by  FIPS  PUB  38.  An  integration  of 
management  and  documentation  procedures  provides  a  necessary  element  of 
control  . 

One  might  emphasize  the  point  that  "The  Job  is  Not  Finished  Until  The 
Paperwork  Is  Done."  The  existence  of  good  standards  does  not  necessarily 
mean  that  they  are  implemented  in  day  to  day  practice.  The  enforcement  of 
standards   requires   a   continual   effort   by  management. 
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KEY   ELEMENTS    IN   THE   ADP    SYSTEM   DEVELOPMENT   PROCESS   AT  HUD 


Dr.  Mar 

Acting  Deputy  Director,  Off 
Department   of  Housing 
Washington , 


in  Goer 

ce  of  ADP   System  Development 
and  Urban  Development 
D.    C.  20410 


The  Office  of  Administration  has  been  restructuring  the  procedures  and 
organizational  responsibilities  associated  with  the  development  of  ADP 
systems  and  operation  of  HUD ' s  ADP  capabilities.  The  basic  intent  of  these 
actions  is  to:  increase  efficiency,  provide  more  responsive  service, 
provide  for  more  orderly  and  systematic  ADP  planning  and  budgeting,  and 
provide  for  the  control  and  accountability  of  our  total  ADP  resource 
utilizat  ion . 

HUD  Handbook  2360.1,  "Planning  Guidance  for  ADP  Data  Systems  Development", 
will  probably  be  superseded  by  a  new  set  of  manuals  which  will  incorporate 
changes  to  accomplish  these  objectives.  In  order  to  provide  HUD's 
programmatic  managers  and  ADP  users  with  guidelines,  and  to  assist  them  in 
continuing  with  their  ADP  development  planning,  while  the  Handbook  is  in  the 
revision  and  clearance  process,  ADPSD  has  prepared  a  description  of  the  ADP 
system  development  cycle  showing  the  traditional  system  development  cycle  as 
it  is  affected  by  the  revised  policies.  This  guidance  should  be  considered 
interim,  even  though  these  same  concepts  are  serving  to  structure  the 
Manual s . 

The  new  Manuals,  when  they  are  issued,  will  incorporate  a  new  conceptual 
approach.  The  ADP  System  Development  cycle  will  be  covered  comprehensively, 
from  Initiation  and  Requirements  Analysis  through  Budget  and  Resource 
Allocation,  Specification,  Design,  Programming,  Test  and  Development 
Implementation,    Acceptance,    Operation,    and  Maintenance. 

The  purpose  of  this  paper,  therefore,  is  to  describe  how  the  ADP  system 
development  process  is  intended  to  be  implemented.  Of  necessity,  the 
description  is  of  a  normal  sequence,  recognizing  that  there  may  be  exception 
conditions   determined   by  overriding  Departmental  priorities. 

The  charts  which  follow  deal  with  four  (4)  major  classes  of  ADP  application 
systems.  While  it  is  always  difficult  to  define  precise  boundaries,  we 
believe  the  definition  of  each  major  classification  is  sufficiently  precise 
to   differentiate   among   the  vast  majority  of  HUD's   ADP  application  systems. 

Application   Systems  Types: 

A.  User  Unique  —  These   applications  have   the   following  characteristics: 

1.  They  are  not  mandated  (Handbook). 

2.  They  are   generally  relatively  small. 

3.  They  generally  do  not   require   routine   and   frequent   use  of 
internal   HUD   computing  capacity. 

4.  They  may   be   "one-time"   or   have   a   short  life-cycle. 

5.  They   generally  address   a   local   or    limited  organizational, 
administrative   or   programmatic  need. 

B.  Single   User/Single   Program  -   These   applications   have    the  following 
characteristics: 

1.  They   are  mandated  (Handbook). 

2.  They   are   for   Department-wide   operation  or  use. 

3.  They  are  devoted   to  a   single  Program   (or   set   of  related  Programs) 
or   a   single   organizational   element    (or   set   of   related  elements 
within   an  organization). 

4.  They   are   generally   operated    in   HUD  equipment. 

5.  They   are   routinely  and   frequently   scheduled    for  operation. 
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6,  They  have  a  relatively   long   forecasted   life  utilization. 

7.  They  are  generally  maintained   and   operated  by  HUD  personnel. 


C,      Single  User /Mu 1 t i-Progr am  or  Organization  -  These  applications  have 
the   following  characteristics: 

1.  They  are  mandated  (Handbook). 

2.  They  are   for  Department-wide  operation  or  use. 

3.  They  are  generally   functionally  oriented,   wherein   the  function 
is   delegated   to  a   single  organizational   element  with  oversight 
or   support   responsibilities   across   Programs  and/or 
organizational  elements. 

They   are  generally   operated    in   HUD  equipment. 
They  are  routinely  "and   frequently  scheduled   for  operation. 
They  have  a  relatively   long   forecasted   life  utilization. 
They   are   generally  maintained   and   operated   by  HUD  personnel. 


D.      Mu 1 t i-User /Mu 1 t i   Program  or   Organization   -   These  applications 
have   the    following  characteristics: 

1.  They   are  mandated  (Handbook). 

2.  They   are   for   Department-wide   operation  or  use. 

3.  They  are  generally   in   support   of  combinations  of  functions 
and   Programs   which   cross   organizational    and  Program 

e lement  s . 

They   are   generally   operated    in  HUD  equipment. 
They   are   routinely  and    frequently   scheduled    for  operation. 
They  have   a   relatively   long   forecasted    life  utilization. 
They   are   generally  maintained   and   operated   by  HUD  personnel 


The  "lead"  responsibility  for  performing  each  task  and  for  developing  the 
system  products,  which  are  enumerated,  is  indicated  by  the  first  code  in 
each  cell.  Tasks  and  products  which  require  support  from,  and  coordination 
with,  additional  organizational  elements  are  indicated  by  the  codes 
following  the  lead  indicator.  (U  =  User  organization,  S  =  ADPSD,  0  =  ADPO,  D 
=  OMI-DBM) 

ADP    SYSTEM   DEVELOPMENT    CYCLE    (BY  TYPE) 


1.      SYSTEM   INITIATION  AND 


REQUIREMENTS  ANALYSIS 

A 

B 

c 

D 

Initiation 

U 

u 

u 

U 

Progr amma  tic  Requirement/Priority 

u 

u 

u 

u 

Operational  Schedule 

u 

u 

u 

u 

Scope/Volume 

u 

u 

u 

u 

Expected    System  Life 

u 

u 

u 

u 

Operational  Concept 

u 

u 

U/S/D 

u/s, 

Designate   Project  Leader 

u 

u 

s 

s 

This  is  the  traditional  first  phase  in  the  identification  of  a  system 
requirement.  Frequently  it  has  been  referred  to  as  "need  identification". 
Included  in  this  phase  is  a  first  estimate  of  benefits  and  costs.  The 
product  of  this  phase  -  "The  Operational  Concept"  -  becomes  an  initial  input 
to  the  planning,  budgeting  and  resource  allocation  processes.  ADPSD  and  OMI 
will   support   Users    in   performing   these   tasks    as  required. 


A  requirement  is  then  merged  with  all  others  and  a  schedule  is  developed, 
priority  established,  and  resources  are  allocated  to  develop  a  system(s)  to 
meet  the  requirement.  Following  these  actions,  the  development  cycle 
cont  inues . 
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2. 


SYSTEMS  SPECIFICATION 


A 


BCD 


Prepare   System  Plan 

U 

U/S/0 

S/U/0 

S/U/0 

Data  Element  Definition 

U 

U/D 

S/U/D 

S/U/D 

Data  Sources 

u 
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Data  Base  Review 
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U/D 

S/D 
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Input  Specification 

U 

U 

S 

S 

Output  Specification 

U 

U 

S 

S 

Staffing  Specification 

U 

U 

U 

U 

Training  Specification 

u 

u 

S 

S 

Concurrence  by  Program  Office 

u 

u 

u 

U/S 

Contractor  GTR   (if  applicable) 

U/S 

s/u 

s 

S 

In  ,this  phase  of  the  development  process  the  requirement  is  defined  more 
precisely,  and  a  system's  operational  characteristics  are  specified.  The 
input  data  and  sources  are  identified  and  reviewed  by  the  Data  Base 
Administration  staff,  the  processing  tasks  are  specified,  etc.  In  addition 
to  the  Data  Base  review  task.  Staffing  and  Training  Specifications  are 
identified  as  discrete  tasks  to  be  accomplished  and  documented.  Obtaining 
the  concurrence  of  the  "end-user"  in  the  system  plan  and  the  specifications 
are  also   identified  as   specific   tasks   in  this  phase. 


COMPUTER   SYSTEM  DESIGN 

A 

B 

C 

D 

General   System  Design 

U 

S 

S 

s 

Input  Processing 

U 

S 

S 

S 

File   Creation   &  Maintenance 

U 
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s 

S 

Output  Processing 

U 

S 

s 

s 

Compu t er / Communi c a t ion  Design 

U 
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Maintenance   &  Operational  Concept 

U 
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S 

s 

s 

These  tasks  comprise  the  basic  computer  system  design  effort  -  sometimes 
referred  to  as  the  "system  architecture".  The  work  is  largely  of  a 
technical  ADP  nature  and  results  in  Design  Documents  in  which  the  structure, 
relationship  and  logic  of  the  various  system  components  are  described.  A 
related  document  is  the  Maintenance  and  Operational  Concept  in  which  the 
hardware  and  application  system  relationships  are  described  and  the 
necessary  operational  conditions,  i.e.,  storage,  line  capacity,  processing 
sequence,  manual  processing  cycles,  etc.  are  documented.  In  addition,  the 
logic  and  discipline  for  the  routine  operation  and  maintenance  of  the  system 
is  described . 


PROGRAMMING 

A 

B 

c 

D 

Inptit  Processor(s) 

U 
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s 

File  Maintenance  Programs 

U 
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Output  Programs 
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Subsystem  Test 

U 
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Total    System  Test 
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Computer   System  Resource  Specs. 

U 

S/0 

s/0 

s/0 

Communication   System  Resource  Specs. 

U 

S/0 

s/0 

s/0 

These      tasks     relate      to      the      actual      programming  and   test   of   the  computer 

programs.      A  resultant   product    is    the   computer     and  Communication  Resource 

Specifications,  basically  a  further  detailing  of  the  equipment  and 
communications   resource  requirements. 
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5. 


TESTING   AND  IMPLEMENTATION 

A 

B 

c 

D 

Operator  Manuals 

U 

S 

s 

s 

Handbooks 

U 

U 

u 

U 

Operator  Training 

U 

S 

s 

s 

Data   Input  Training 

U 

s 

s 

s 

Program/Manager  Training 

U 

u/  s 
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u/s 
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TT 
U 
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Pilot  Test 
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Test  Evaluation 

u 
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User   Support  Plan 

u 
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In  this  phase  of  the  cycle  the  system  products  are  subjected  to  test.  In 
order  to  accomplish  the  test  (either  for  Field  or  CO  systems)  the  supporting 
training  and  documentation  tasks  must  also  be  accomplished,  and  coordinated 
planning  must   take  place. 


ACCEPTANCE,    TURNOVER,  OPERATION 
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Before  a  system  is  released  for  operation,  the  conditions  which  define 
acceptability  must  be  determined  (along  with  measures),  and  tests  conducted 
to  demonstrate   their  achievement. 


7. 


SYSTEM  MAINTENANCE 

A 
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U 
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U 
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The  system  is  now  in  the  operational  inventory,  and  is  being  utilized  in 
accordance  with  the  operational  concept  and  specification  previously 
defined.  All  systems  require  continuous  attention,  and  must  be  periodically 
refined  to  suit  changes  in  operational  needs.  In  most  instances,  major 
changes  to  existing  systems,  to  incorporate  new  functions  or  to  broaden  the 
scope  of  coverage,  will  recycle  through  the  development  process  starting 
with   the    Initiation  Phase. 
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SYNOPSIS   OF   QUESTIONS   AND   ANSWERS   FROM   PARALLEL   SESSION  A 


Greg  Loss 

Public   Health  Service 


Tom  Kurihara 

Agricultural  Stabilization  & 
Conservation  Service 


Que  s  t  ion : 

Is      there      an     awareness   by  management   of   the   cost   of   implementing  standards 

such   as   FIPS   PUB   38?      My   experience   has   been   that   a     r u 1 e-o f- thumb  estimate 

to     be   added   to   the   cost   of   a   project    for   documentation   of   a   large  system  is 

20-30%.  This  is  not  excessive,  however,  the  realization  of  the  cost  of 
documentation  must   be  addressed. 


Smith ; 

Agree  that  there  is  an  additional  cost. 
McGr eer  : 

be 


a   history   of   the   cost   of  documentation. 


There   doesn't   appear  to 
Head  : 

Is    there   a   danger   of   over-documentation?      In  USDA,    the   Application  Inventory 
Forms   were   developed    to   obtain   information    from     the      agencies      in     USDA  on 
major     applications.      We  were   concerned   with   compliance   and    the  implications 
of   too  much  documentation. 
Audience   Comment : 

Must      look   at   documentation   costs    in   perspective,    i.e.,    there    is   a   danger  in 
looking   at    the    "front-end"   costs   only,    whereas    taken   as   part   of   the   cost  of 
the      system  over    its   entire    life,    the   cost   of   documentation   is    in   its  proper 
perspective. 
Smith : 

Compare      training     and     education     costs    to   documentation   costs.      Aren't  the 
training   and   education   costs   of   an   organization   justified    in     terms      of  the 
return   gained    from   the  investment? 
Goer  : 

At      HUD,      we     have      tried      to      address      the      problem  of   cost   by  establishing 
criteria   for   the   amount    of   documentation,    as   described    in  my  presentation. 
Kur  ihar a : 

Documentation  is  the  end  product  of  the  system  development  activities.  It 
serves  as  a  record  of  what  decisions  were  made.  TG  14  did  not,  because  of 
its  limited  scope,  address  the  system  development  activities  or  the 
management  activities.  Given  a  management  process  with  estimation 
techniques,  the  cost  of  documentation  can  be  tied  to  management  and  project 
activities,  and,  therefore,  be  placed  in  its  proper  perspective. 
Head  : 

In     my   experience,    in   recent   years,    I   don't    recall    that   management   has  asked 
about    the    cost   of   documentation   and  training. 
McGr eer  : 

The  costs  must  be  addressed,  because  we  need  top  management  support  of  the 
standards  development  effort.  There  is  the  danger  that  as  soon  as  a 
successful  standards  effort  is  developed,  such  as  in  the  Department  of  Navy, 
there  is  a  tendency  to  downgrade  the  Standards  Group.  Top  management  should 
be  provided  with  the  potential  savings  resulting  from  a  successful  standards 
development   and   maintenance  effort. 


bring  to  top  management  attention  the  need  for 
the   cost   of   not   having  it? 


Que  s  t  ion : 

Has  anything  happened  to 
documentation   standards  and 

McGr eer : 

There  is  the  example  of  the  computer  security  reporting  requirements.  Top 
management  attention  was  obtained  when  a  GAG  report  was  issued.  I  know  that 
we  can't  always  go  up  to  GAO  and  down  the  ladder  again  to  get  top  management 
attention  on  everything.  Go  to  your  top  management  and  ask  for  their 
support,    CRUSADE    for   recognition    to   save   money   in   the    long  run. 
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Goer ; 

Again,  we  are  in  a  political  environment.  There  is  a  tendency  to  want  to 
hurry  and  expedite  systetna  development  because  some  senior  managers  want  to 
make  an  impact  quickly  and  leave  it  to  the  bureaucracy  to  tidy  up  later. 
The  bureaucracy,  in  the  long  run,  must  document  to  maintain  the  systems 
developed  as  quick  solutions. 
Audience   Comment : 

I  review  the  systems  on  paper,  i.e.,  documentation,  as  a  regular  part  of  my 
job.  The  basic  authority  is  derived  from  the  Budget  and  Accounting  Act  of 
1950,  wherein  GAO  has  the  responsibility  for  approval  of  all  budgeting  and 
accounting  systems.  There  is  a  need  for  more  management  pressure  to  develop 
documentation  standards. 
Head : 

We     appear     to   be   a  group  of  computer  professionals   talking.     Are  we  talking 
to  each  other,    or   is   top  management  here   to  benefit   from  this   joint  selling 
effort   by  NBS   and  CSC? 
Audience  Response : 

Have  to  use  the  " c ar r o t / s t i ck"  approach.  Prepare  good  documentation  during 
the  implementation  stage,  and  present  it  to  top  management  for  their 
decision  on  continuation  of  the  project.  Show  how  good  documentation 
supports  the  decision  making  process,  and  provides  a  basis  for  potential 
cost  savings  or  avoidance. 
Head  : 

USDA  is  committed  to  the  life  cycle  concept  with  what  we  call  "creeping 
commitment"  via  project  documentation.  Documentation  is  the  mechanism  by 
which  projects  are  reviewed  at  each  stage  and  phase  of  application 
development.  It  is  the  means  of  bringing  management  back  into  the  decision 
cycle  as  you  go  on. 
Goer  : 

Good  documentation  can  be  your  protection  against  GAO  reports.  On  the 
positive  side,  programming  is  still  an  "art-form."  As  a  writer,  a 
programmer  is  forced  to  write  with  increased  precision  and  definition  when 
describing  the  computer  program.  Managers  get  better  controls  and  avoid 
surprises  as  better  documentation  is  provided.  Real  benefit  to  management 
at   all    levels   is  control. 


Que  8  t  ion : 

What   is   the  cost? 


Goer : 

The     price  of   documentation   in   the  process   of  delivering  a   completed  product 
is   really  a   "sunk  cost"   in   the  bureaucracy.     What   is  most   important   to  me  in 
the     control     I     have   over   that   process  when  good   documentation   is  available 
for   each   decision  point   in   the   life  cycle. 
Head  ; 

We  should  move  on  to  avoid  the  preoccupation  with  cost.  In  any  self- 
regulating  mechanism,  as  dollar  costs  increases,  a  method  of  getting 
management  involvement  evolves.  Richard  Nolan's  Harvard  Business  Review 
Article  "Managing  the  Four  Stages  of  EDP  --  Growth  and  Preparing  for  the 
Fifth  Stage"  describes  the  stages  of  EDP  development  and  the  different 
degrees  of  management  involvement. 

Question : 

Has  the  valtie  of  documentation  been  addressed  in  respect  to  computer  program 
maintenance?  The  savings  resulting  from  improved  maintenance  productivity 
can  decrease  the  number  of  maintenance  programmers,  and  add  to  the 
development  group. 

Goer  : 

Usually  what  happens,  because  of  the  political  climate  we  are  exposed  to,  is 
that  if  an  estimate  is  made  to  management  of  eight  months  with 
documentation,      or   six  months  without,    they  will   say  go  with   the   six  months'. 
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Head; 

In  the  Federal  Government,  in  my  experience,  there  is  a  general  lack  of 
continuity  between  the  requirements  statement  and  maintenance  of  the 
program.  The  primary  concern  is  to  get  it  up  and  running,  and  avoid  the 
issue  of  maintenance.  On  the  other  hand,  there  is  a  greater  concern  for 
continuity  of  development  and  maintenance  for  commercially  developed 
s  o  f  twar e . 
McGreer : 

Take  the  life  cycle  approach.  The  cost  of  documentation  is  repaid  over 
time.  The  SAGE  system  maintenance  problem  was  created  as  a  result  of  having 
a  cascading  series  of  different  equipment  driving  the  automatic  projection 
at  the  command  center.  The  programs  had  to  contain  performance  profiles  for 
aircraft  and  weapons  systems.  Changes  were  needed  as  aircraft  and  weapons 
changed.  The  cost  savings  were  realized  in  making  the  changes  more  easily. 
Audience  Comment: 

I  think  I  have  a  feel  for  the  maintenance  cost.  In  our  organization,  I  run 
only  a  maintenance  shop,  we  do  not  accept  any  software  for  maintenance  from 
the  development  shop  without  usable  documentation.  We  use  our  standards  as 
a  basis  for  judgment.  Of  course,  there  are  roughly  four  orders  of  magnitude 
in  documentation  and  maintenance.  It  goes  from  the  1401/650  programs  still 
being  run,  which,  taken  overall,  takes  2  man-years  to  maintain;  to  the  well 
documented   system,   which    can  be    changed   in   a   day   or   two  per  month. 

Question   for  Mr.    Head   and  Dr.  Goer; 

How  does  your  agency  currently  control  and  audit  your  Department's 
compliance  with  your  standards  program?  What  plans  do  you  have  in  the 
future    for   this  control? 

Head  ; 

In  USDA,  we  work  closely  with  the  internal  Office  of  Audit  (OA)  staff.  OA 
is  staffing  up  to  be  able  to  address  auditing  of  the  system  development 
process.  We  have  had  to  be  careful  to  avoid  ove r- do cume n t a t i on ,  and 
therefore  tried  to  establish  threshold  values  for  submitting  application 
documentation  for  approval;  e.g.,  not  for  systems  with  an  annual  cost  of 
less  than  $25,000. 
Goer  : 

Our  problem  is  smaller  and  easier  to  manage.  The  Assistant  Secretary  for 
Administration  is  charged  with  the  responsibility  for  controlling  systems 
used  strictly  within  his  area  of  responsibility.  We  do  that  through  a  staff 
function  which  combines  standards,  quality  assurance,  and  quality  control. 
He  cannot  control  systems  which  are  being  developed  in  other  areas  under  the 
other  Assistant  Secretaries. 
Smith  ;' 

One     agency     I      surveyed      ran   uncertified   programs    as    stand-alone   jobs  until 
they   could  be    certified.      They  would   then  be   eligible    for   cataloging   to  the 
productionlibrary. 
Audience  Comment; 

We  at  GAO  visit  various  agencies  to  review  systems  and  to  assess  the 
readiness    of   documentation   prepared   in   support   of   computer  systems. 

Question    for  Dr.  Goer; 

You  mentioned  that  you  do  not  document  those  systems  which  prepare 
Congressional  reports.  In  those  instances  where  Congress  might  find  the 
system  useful,  and  in  fact,  decide  to  fund  on  a  priority  basis,  how  do  you 
then  go  back   and  document? 

Goer; 

One      time    requests    for    retrieval  are    recorded   for   effort   and  accomplishment, 

but   are   not   documented.      Because  they   are   one    time   data  extractions  through 

a   DBM   language,    a   new   DB   was   not  created. 

Question; 
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Are  states  expected  to  comply  with  these  standards  (FIPS  PUB  38)  on  systems 
developed  with,    or   supported  by,    Federal  funds? 

McGreer : 

Over      time,    there   will   eventually  be   some    type   of   compliance,    if   the  Privacy 
Act   of    1974   can  be   used   as    an   example.      The   efficiency     considerations  will 
eventually   push    in   that  direction. 
Head  ; 

I     believe      that   0MB   Circular  A-90    specifically   addresses    that   question.  It 
prohibits    any   strings    to  be    attached   to   grants,      or     on     other  requirements 
levied  by   the   Federal  programs. 
Kur ih ara  : 

There  is  a  non-profit  firm.  Public  Technology,  Inc.,  which  is  assisting 
local,  municipal,  and  state  governments  on  the  exchange  of  technology  under 
the  sponsorship  of  HUD.  They  have  developed  some  documentation  standards 
for  exchange  of  information  about  computer-based  systems.  Generally,  the 
concepts  are  transferred,  and  the  implementation  of  a  transferred  system  is 
accomplished  with  sufficient  changes  to  suit  the  receiving  organization. 
But  there  is  a  tangible  benefit  of  having  standard  documentation  guidelines 
as  a  supplement  to  personal  contact.  The  participating  local,  municipal, 
and  state  government  representatives  all  agreed  that  the  standards  developed 
in  their  group  will  be  beneficial.  A  member  of  FIPS  TO  14  was  an  observer 
at    the   working   group  sessions. 

Question : 

How  IS  TG  14  organized  to  assist  in  using  FIPS  PUB  38?  What  is  the  schedule 
for   issuing   the   feasibility   study,    cost  benefit   analysis  guidelines? 

Kur ih  ara : 

Thank     you      for   providing   us   with    the   opportunity   to   announce    the  activation 
of   a  subgroup    chaired   by  Mr.    Roy   Young,    DHEW ,    to   provide    assistance    to  users 
of  FIPS   PUB    38.      We    are    ready    to   provide    the    required  assistance. 
Audience    Comment : 

The  review  process  in  the  maintenance  of  the  DOD  standard  has  worked.  It 
can  v;ork  the  same  way  at  the  Federal  level.  We  are  now  working  on  the 
second  revision  to  4120-17M.  The  first  revision  is  in  the  publication 
process.  As  people  get  more  familiar  with  the  standard,'  they  have  more 
input  to  it  and  we  are  continously  getting  new  ideas.  (For  further 
information,    contact    Don  Wagus,    US   Army   Computer   Systems    Command,  664-4411). 


Head  ; 

In     closing,      I     will   use    the    5   questions    listed   on    the   symposium  program  to 
try   to   review  what  we  discussed. 
Can   the   guidelines  help? 

-  A  qualified   YES.      There    is    a  need    to   seek  management    review   at  the 
ADP   policy  level. 

-  How   can    the  manager   evaluate    technical  documentation? 

Levels   of   documentation    standards    should   be   identified  with    the  lower 
levels,    so    that    top   management   can  handle   onlj'    the   appropriate  details. 
Is   documentation   worth    the  cost? 

Much    concern   and   preoccupation  with   cost.      Benefits    can  be  obtained 
by  making   presentations    to   top  management,    showing   that   the  series 
of   documents   produced   during   the   development   period   are    a  means  of 
clarifying   requirements,    improving   the   effectiveness    of   the  develop- 
ment  effort,    and   easing   the   maintenance    of  systems. 

-  How   can   software   quality  be   assured    through  documentation? 

A  better   understanding   of   software    results    from  improved  documentation. 

-  Do   existing   systems   need    to   be  documented? 

Existing   systems   need    to  be   documented   as   changes    are   made.      For  the 
technical   people,   you  must    devise   methods    of   getting  management  atten- 
tion  to   support   good    and   complete  documentation. 
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INTRODUCTION:      ADP    SYSTEMS,    OPERATIONS,    AND   PROGRAMMER  PERSONNEL 


Thomas  Giammo 
Social    Security  Administration 
Health,    Education,    and  Welfare 
Baltimore,    Maryland  21235 


Welcome  to  Session  B  -  "ADP  Systems,  Operations,  and  Programmer  Personnel"  - 
As  one  can  tell  from  the  title,  th-is  session  is  designed  to  explore  those 
aspects  to  FIPS  PUB  38  which  affect  the  working  level  personnel  of  a  data 
processingoperation.  , 

My  name  is  Tom  Giammo,  and  it's  my  function  to  serve  as  moderator  of  this 
session.  Before  introducing  the  members  of  the  panel,  I  would  like  to  go 
over   some   of   the   ground   rules    I    intend    to    follow  in   this  session. 

First  of  all,  I've  asked  that  the  discussion  and  question/answer  phase  of 
the  session  not  be  taped.  The  introductory  addresses  of  the  panel  members, 
however,  will  be  taped,  to  assist  in  the  preparation  of  proceedings. 
Although  it  would  have  been  helpful,  in  this  regard,  to  tape  the  discussions 
(since  a  synopsis  of  these  will  also  appear  in  the  proceedings),  I  felt  that 
it  might  tend  to  inhibit  open  discussion.  The  primary  purpose  of  this 
session  is  to  initiate  a  frank  and  open  dialogue  between  TG-14  and  the  FIPS 
PUB  38  "user  community".  To  accomplish  this  purpose,  it  is  necessary  that 
negative  opinions,  unflattering  examples  of  current  practices,  etc.  -  all  be 
freely  expressed,  without  fear  that  such  remarks  might  be  traced  to  any 
individual . 

Secondly,  I've  asked  the  panel  members  to  lead  off  the  session  with 
presentations.  I  would  like  to  ask  that  no  questions  be  initiated  during 
these  presentations,  since  they  are  scheduled  to  last  the  entire  "pre-lunch" 
period.  I  hope,  however,  that  you'll  be  able  to  save  all  your  questions 
until  our  "after-lunch"  period,  when  I'll  turn  the  floor  over  to  the 
audience . 

Let  me  begin  by  giving  you  some  information  about  myself  and  the  panel.  I'm 
currently  with  the  Social  Security  Administration,  where  I'm  responsible  for 
the  data  processing  center,  which  services  the  statistical,  administrative, 
and  management  functions  of  SSA,  We've  begun  to  feel  the  impact  of  FIPS  PUB 
38  in  my  organization,  and  have  already  begun  to  extend  parts  of  the 
guidelines  to  cover  our  specific  procedures.  My  association  with  FIPS  PUB 
38  and  TG-14  goes  back  much  further  than  that,  however.  In  the  mid-1960's, 
I  had  the  dubious  honor  of  being  one  of  the  "guinea  pigs"  used  by  NAVCOSSACT 
to  try  out  the  initial  draft  of  their  documentation  standards.  At  that 
time,  I  headed  the  Washington  office  of  a  software  consulting  firm  which  had 
a  contract  with  NAVCOSSACT.  Although  we  had  severe  problems  with  this 
standard,  I  was  intrigued  with  the  possible  advantages  (not  only  to 
NAVCOSSACT,  but  also  to  the  vendor)  of  such  standards.  Consequently,  we  put 
a  lot  of  effort  into  our  comments  on  the  standards,  and  worked  closely  with 
the  NAVOCCACT  personnel  on  testing  revisions.  As  time  went  on,  and  the 
standards  improved,  my  initial  optimistic  appraisal  of  the  potential 
benefits  was  confirmed,  and  1  became  an  enthusiastic  supporter  of  the 
standards.  As  most  of  you  know,  these  NAVCOSSACT  standards  became  the  basis 
of  NAVY-wide  standards,  which  in  turn  became  the  basis  of  DOD-wide 
standards,  which  in  turn  were  the  starting  point  of  TG  14's  efforts  with 
FIPS   PUB  38. 

This  brings  me  to  our  first  panel  member.  Bob  Hegland.  Mr.  Hegland 
represents  the  single  thread  of  continuity  through  the  entire  evolution  of 
FIPS  PUB  38,  from  the  initial  NAVCOSSACT  standards.  I  met  Bob  back  in  the 
mid-60's,  and  since  then  I've  stayed  abreast  of  the  documentation  standards 
field      through     him.        He     was      an   active   member   of   each   of   the  intermediate 
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standards  groups  (NAVCOSSACT,  NAVY,  DoD) ,  and  is  a  key  member  of  TG-14.  Bob 
is   still  with  NAVCOSSACT,    in  the  documentation  standards  area. 


Mr.  Shirley  Alger  is  a  co-worker  of  mine  at  the  Social  Security 
Administration.  I've  asked  him  to  be  a  member  of  the  panel  because  he 
represents  essentially  the  entire  sum  and  total  of  the  Social  Security 
Administration's  experience  with  the  implementation  of  FIPS  PUB  38,  at  this 
stage.  He  has  been  given  the  task  of  organizing  the  programming 
documentation  standards  activities  of  the  Office  of  Management  and 
Administration.  He  chose,  I  think  properly,  to  attack  this  responsibility 
with  the  aid  of  FIPS  PUB  38,  His  experiences,  so  far,  are  valuable,  in  that 
he  has  run  into  some  of  the  difficulties  all  of  us  will  encounter.  Some  of 
the  ways  in  which  he  is  going  about  trying  to  solve  these  problems  will  be 
instructive.  Most  important,  there  is  at  least  a  touch  of  the  real  world  in 
his  experiences.  They  may  prepare  you  for  what  will  really  happen  when  you 
try  to  put  these  guidelines  into  the  form  of  a  standard  to  be  used  by  your 
or ganizat  ion . 

Mr.  Herb  Bright  is  well  known  to  anyone  who  has  been  involved  with  ADP 
standardization.  Herb  has  made  many  significant  contributions  to  computing 
in  general,  and  I  felt  his  broad  range  of  experience  would  be  useful  to  draw 
upon.  I  especially  asked  Herb  to  join  the  panel  because  he  comes  from 
outside  the  federal  government.  He's  currently  President  of  Computation 
Planning,  Incorporated,  which  is  a  private,  software-oriented,  consulting 
firm,  I  think  Herb's  experiences  in  using  various  government  documentation 
standards  will  be  of  interest  to  anyone  documenting  software  using  the  FIPS 
PUB  38  Guidelines, 

It  is  my  view  that  the  purpose  of  this  session  is  to  create  a  general 
awareness  of  the  problems  associated  with  the  implementation  of  the 
guidelines,  in  the  form  of  standards  for  individual  agencies,  departments, 
etc.  What  I  hope  we  can  explore,  in  some  depth,  is  the  considerations  which 
management  ought  to  be  aware  of  before  committing  their  organizations  to  the 
guidelines.  It  is  my  personal  feeling  that  it  would  be  most  detrimental  for 
management  just  to  take  the  naive  attitude  that  the  existing  guidelines  can 
be  "adopted"  as  standards  by  simply  issuing  a  memo  to  that  effect.  That 
kind  of  approach  will  not  only  have  the  immediate  effect  of  failure,  but  is 
bound  to  have  a  longer  term  effect  of  convincing  people  that  the  concept  of 
documentation  standards  itself  is  faulty.  If,  in  this  session,  we  can 
meaningfully  explore  some  of  the  more  important  of  the  management 
considerations  which  should  be  part  of  the  implementation  of  the  FIPS  PUB  38 
Guidelines,  I  would  feel  that  we  have  had  a  successful  session,  well  worth 
the   time   and   effort   of  everyone  involved. 

In  trying  to  shape  this  session  toward  that  goal,  we  each  have  distinct 
roles.  I  have  the  easiest  role  of  all.  As  session  chairman,  it's  my 
responsibility  merely  to  state  the  problem  and  to  "oversee"  the  resultant 
discussion,  (I  don't  intend  to  be  too  rigorous  about  overseeing  the 
discussion  -  if  the  group's  excitement  and  enthusiasm  is  so  great  that  the 
session  gets  out  of  hand,  I  think  we  would  be  achieving  our  original 
purpose,)  The  panel  members  are  here  to  start  the  discussions.  Their 
presentations  are  intended  to  explore,  only  partially,  limited  aspects  of 
the  problem.  In  the  open  discussion  period,  I  hope  to  have  them  serve  as  a 
target  for  your  questions  and  as  a  foil  for  your  opinions.  You,  the 
audience,  have  the  most  important  role,  I  expect  you  to  lead  the 
d i s c u s s ion , cha 1 1 enge  the  views  of  the  panel,  explore  unaddressed  aspects, 
recount  relevant  experiences,  suggest  alternatives,  etc,  I  want  to 
emphasize  that  I  will  positively  encourage  alternate  viewpoints,  criticisms 
of  the  guidelines,  etc.  There  is  a  natural  tendency  in  conferences  such  as 
this  to  have  only  the  enthusiastic  "boosters"  do  all  the  talking.  The  panel 
and  I  are  obviously  biased  in  this  direction  -  we  wouldn't  have  been  invited 
here  unless  we  weren't  already  associated  with  documentation  standards,  I'm 
going   to   insure   that  we  don't  monopolize   this  discussion. 
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To  start  off  the  presentations,  I've  prepared  a  few  slides  which  give  my 
view  of  the  important  aspects  of  problems  in  the  implementation  of 
documentation  standards  from  the  FTPS  PUB  38  Guidelines.  In  the  hope  of 
creating  a  common  basis  of  discussion  I  have  previously  distributed  these  to 
the  panel  members  and  asked  them  to  at  least  consider  them  in  drafting  their 
presentations.  I  also  intend  to  return  to  these  topics  in  my  final 
summarization   at    the   conclusion   of   the  session. 

(Transcription  of   slides   in   lieu  of   text   of  remainder   of  presentation.) 
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SLIDE  I 


SCOPE 

o     IDENTIFY   POTENTIAL   PROBLEM  AREAS 

o     EXPLORE   INTERACTION  WITH  DOCUMENTATION  GUIDELINES   AT  WORKING  LEVEL: 

-  ARE   THE   GUIDELINES   GENERAL   ENOUGH   IN  SCOPE? 

-  ARE   THE   GUIDELINES   TOO  ABSTRACT   TO  APPLY    IN  PARTICULAR  CASES? 

-  ARE   THE   GUIDELINES   COMPREHENSIVE   ENOUGH   TO  PRODUCE  SATISFACTORY 
DOCUMENTS? 

-  DO   THE   GUIDELINES   PROVIDE   A  NATURAL   INCENTIVE   FOR   ACCEPTANCE  BY 
ASSISTING   THE    "WORKERS"    IN   THEIR  RESPONSIBILITIES? 

o     DISCUSS   APPROACHES   TO  PARTICULAR  PROBLEMS: 

-  ADAPTATION   OF   GUIDELINES   TO   PARTICULAR  WORKING  ENVIRONMENTS 

-  SYSTEMS,    OPERATIONS,    PROGRAMMER   FAMILIARIZATION   AND  TRAINING 

-  ELIMINATION   OF   "PASSIVE  RESISTANCE" 

SLIDES    II, III, IV,    &  V 

DISCUSSION  TOPIC  "SEEDS" 

o      ARE   THE   GUIDELINES   GENERAL   ENOUGH    IN  SCOPE? 

-  DO   THEY   CAPTURE    THE   ESSENTIAL   ELEMENTS   OF    SYSTEMS  ENCOUNTERED 
IN   THE    "REAL  WORLD"? 

-  ARE   THEY   TOO   BATCH-PROCESSING  ORIENTED? 

o      ARE   THE   GUIDELINES    TOO   ABSTRACT   TO   APPLY    IN   PARTICULAR  CASES? 

-  CAN  WORKING   LEVEL   PERSONNEL   RELATE   THEIR   INFORMATION  INTERFACE 
REQUIREMENTS   TO   THE    CONTENT    SPECIFIED    IN   THE  GUIDELINES? 

-  SHOULD   THEY   BE   REINTERPRETED,    EXPANDED,    MODIFIED   TO  MATCH  LOCAL 
ENVIRONMENT? 

o      ARE    THE    GUIDELINES    COMPREHENSIVE  ENOUGH? 

-  ARE   ALL   THE   ELEMENTS   OP  A   SYSTEM  WHICH   REQUIRE  DOCUMENTATION 
ADEQUATELY  ADDRESSED? 

-  WILL   DOCUMENTATION   PREPARED   IN   ACCORDANCE   WITH   THE  GUIDELINES 
BE  SATISFACTORY? 

o      DO   THE   GUIDELINES   PROVIDE   A   NATURAL    INCENTIVE   FOR,  ACCEPTANCE  BY 
ASSISTING   THE    "WORKERS"    IN   THEIR  RESPONSIBILITIES? 

-  WHAT   DO   THE   GUIDELINES   DO   FOR   THE   PROGRAMMERS,  OPERATIONS, 
SYSTEMS  PERSONNEL? 

-  WHAT   FAMILIARIZATION,    TRAINING,    ETC.    IS  NECESSARY? 
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PROBLEMS    IN   USING   THE    DOCUMENTATION  GUIDELINE 


Robert   R.    Hegland  * 
Naval    Command   Systems   Support  Activity 
(Code  70.3) 


I .  INTRODUCTION 

The  items  that  follow  contain  a  discussion  of  some  of  the  problem  areas  that 
have  been  raised  in  the  past  regarding  computer  program  documentation 
standards  and  guidelines.  Most  of  these  problem  areas  can  be  resolved;  some 
cannot*  There  are  few  standard-s  or  guidelines  that  are  perfect  and  about 
which  no  questions  can  be  raised.  The  guidelines  contained  in  FIPS  PUB  38 
are  the  product  of  not  only  the  FIPS  committee,  but  also  of  many  other 
committees  and  individuals  who  have  worked  with  its  predecessors.  Each  of 
these  committees  raised  questions  and  resolved  them  by  changing  and 
enhancing  the  documentation  system.  A  characteristic  of  a  guideline  such  as 
FIPS  PUB  38  is  that  it  must  be  reviewed,  updated,  and  changed  as  our 
experience  grows. 

II.  AUTOMATED   RUN  INSTRUCTIONS 

Some  organizations  now  generate  what  they  call  Automated  Run  Instructions 
from  the  run  streams  of  their  programs.  They  have  asked  if  this  removes  the 
need  to  produce  an  Operations  Manual.  It  is,  of  course,  up  to  the  central 
office  or  the  implementing  organization  to  review  this  question  in  detail 
and  determine  whether  all  of  the  items  of  information  in  the  Operations 
Manual  are  covered  by  the  Automated  Run  Instructions.  My  reaction  is  that 
there  are  certainly  some  parts  of  the  Operations  Manual  that  can  be  replaced 
by  such  run  instructions.  There  are  other  parts,  however,  that  are  probably 
not  a  part  of  the  run  instructions,  such  as  the  Program  Inventory,  some  of 
the  information  about  the  Output  Reports,  and  information  about  Non-Routine 
Operations    and   Remote  Operations. 

III.  REAL-TIME,  ON-LINE 

Systems  that  perform  real-time,  on-line  operations,  and  that  may  have  a 
fully  dedicated  computer  to  run  them,  have  always  been  a  problem  to  document 
in  terms  that  users  can  understand,  since  the  documentation  must  be 
sequential,  and  the  programs  can  run  in  different  sequences.  Whenever 
possible,  with  these  types  of  systems,  it  seems  to  be  a  good  idea  to  build 
as  much  tutorial  information  into  them  as  possible.  There  doesn't  seem  to 
be  any  all-encompassing  solution  to  this  problem  for  the  User's  Manual.  The 
Program  Maintenance  Manual  can,  of  course,  still  be  written  as  shown  in  the 
Guideline,  since  it  can  be  sequenced  by  program  or  module.  The  Operations 
Manual  would  need  to  be  quite  different  from  that  in  the  Guideline,  since 
there  is  very  little  operator  intervention  or  action  required  in  most  of 
these  systems.  Instead,  the  terminal  operator,  who  is  really  a  "user",  has 
significant  control  over  what  is  largely  operator  functions  in  nonterminal- 
oriented  systems. 

IV .  STRUCTURED  PROGRAMMING 

The  question  has  been  raised  in  the  past  about  whether  this  documentation 
system  can  be  used  to  support  structured  programming  projects.  The  general 
feeling  on  several  committees  is  that  there  is  no  essential  difference  in 
documenting  structured  programs  and  programs  written  using  other  techniques. 
As  a  matter  of  fact,  a  large  contractor  looked  at  that  problem  with  the  DoD 
version  of  the  documentation  standard,  and  had  only  a  very  few  changes  to 
recommend.  Most  of  these  changes  did  not  have  a  significant  impact  on  the 
DoD  standard. 

V.  COBOL 

The  statement  has  often  been  made  that  COBOL  is  " s e 1 f -documen t ing "  and  the 
question  has  been  raised  as  to  how  this  relates  to  the  documentation 
Guideline.        COBOL   is    certainly  written   in  English-like    statements,    and  that 
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is  a  great  aid  for  a  programmer  who  is  trying  to  determine  what  the  program 
is  doing.  With  COBOL,  there  is  still,  however,  a  need  to  prepare  a  Program 
Maintenance  Manual  (particularly  for  a  large  system),  since  a  new  programmer 
still  needs  a  narrative  overview  to  use  in  becoming  familiar  with  the  basic 
structure  of  the  program  system.  There  is  no  need,  in  the  Program 
Maintenance  Manual  of  a  COBOL  program,  to  include  a  detailed  narrative  of 
the  logical  flow  of  the  program.  COBOL  is  not,  however,  "self-documenting" 
for  a  user  to  read  or  for  a  computer  operator.  Consequently,  there  is  still 
a  need  for  written  documents  for  these  functions.  Since  COBOL  is,  to  some 
extent,  self-documenting,  then  if  the  program  has  been  well  commented,  less 
detail  needs  to  be  included  in  a  written  document  on  the  program  than  would 
be  needed  if  the  program  were  written  in  a  less  familiar  language  or  in 
machine  language. 

VI .      PROGRAM  MAINTENANCE  MANUAL 

There  has  been  a  proposal  that  the  Program  Maintenance  Manual  isn't  really 
needed,  and  that  it  should  be  replaced  by  the  Program  Specification,  which 
was  written  during  development,  and  kept  up  to  date  as  the  programming 
progressed.  The  Program  Maintenance  Manual,  of  course,  serves  several 
purposes,  such  as  to  support  the  transfer  of  the  system  to  another 
organization,  or  in  training  new  programmers  in  maintaining  the  system.  The 
approach  of  using  the  Program  Specification  as  the  Program  Maintenance 
Manual  can  be  made  to  work,  but  there  are  some  very  real  problems  in  doing 
so.  First,  it  means  that  a  Program  Specification  would  have  to  be  written 
during  the  development  of  each  and  every  system.  Using  this  approach  also 
means  the  Program  Specification  would  have  to  be  updated  constantly  as  the 
system  was  developed.  This  updating  seems  to  be  difficult  to  do  in  the  real 
world.  This,  again,  is  something  that  a  central  office  needs  to  look  at 
very   carefully    in   implementing    the  Guideline, 

VII  ,  TERMINOLOGY 

One  of  the  continuing  problems  with  this  Guideline,  and  with  all  guidelines 
standards,  is  that  the  terminology  may  mean  different  things  to  different 
organizations.  For  example,  a  "system"  means,  to  some  people,  the  hardv/are 
and  software;  to  others,  the  term  means  the  application  system  being 
programmed.  This  Guideline  has  been  written,  as  much  as  possible,  using 
basic  ADP  terms  that  have  generally  accepted  meanings  across  all 
organization  lines.  If  input  is  received  from  a  satellite,  for  example,  it 
is  still  input;  the  fact  that  it  comes  from  a  satellite  won't  be  mentioned 
in  the  Guideline,  A  related  problem  in  all  guidelines  and  standards  is  that 
they  must  be  written  in  English.  Even  though  we  have  a  standard  Dictionary 
for  Information  Processing,  we  still  have  to  use  English  to  communicate  our 
thoughts  and  ideas,  and  English  is  an  imprecise  language  that  allows  what 
one  person  writes  to  be  interpreted  differently  by  another  person.  In  using 
the  Guideline,  authors  should  remember  that  it  was  written  to  cover  as  many 
different  organizations  and  situations  as  possible.  It  is  necessarily 
subject  to  interpretation.  Authors  should  try  to  fit  what  is  included  in 
the   Guideline    into    their   own  environment. 


VIII.  CONCLUSION 

Problems  perceived  in  using  the  Guideline  depend  on  how  thoroughly  it  has 
been  reviewed  and  understood,  both  by  the  authors  and  the  implementing 
central  office.  Some  problems  are  harder  to  resolve  than  others,  but  the 
central  office  needs  to  anticipate  as  many  problems  and  questions  as 
possible,  so  that  implementation  guidelines  can  be  promulgated  at  the  same 
time  as  the  Guideline.  Many  of  the  problems  that  arise  are  those  that  have 
already   been   addressed   and   discussed    in   Section   2   of   FIPS   PUB  38. 

*       The     comments    contained   herein   are   the   author's,    and   do   not  necessarily 
represent   policy   of   the   Department   of   the   Navy   or   of   any   naval  activity. 
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SYNOPSIS   OF   QUESTIONS   AND   ANSWERS   FROM   PARALLEL   SESSION  B 


Robert   A.    Mattes  & 
Social    Security  Administration 


Kenneth  Rodey 

National    Security  Agency 


Question : 

There  appears  to  be  a  lack  of  guidelines  to  instruct  individuals  on  how  to 
handle   changes    in   the   Maintenance   Manual.      Was    this  deliberate? 


Panel   Member : 

YeSj  the  guidelines  were  omitted  intentionally,  to  allow  each  organization 
the  opportunity  to  develop  its  own  administrative  procedures  for  handling 
changes  to  the  Maintenance  Manual.  It  was  assumed  that  each  organization 
handles  the  posting  of  changes  differently  (e.g.,  change  pages,  complete 
r ewr  i  t  e ,  etc.). 
Panel   Member : 

Because  of  the  large  investment  in  Application  Programming,  there  is  a 
definite  need  for  a  reliable  access  audit-trail,  to  protect  programs  from 
being  modified  without  maintaining  a  documented  record  of  those 
modifications.  However,  there  is  currently  very  little  attention  being  paid 
to  this  matter.  In  general,  subtle  changes  to  computer  programs  are  not 
backed  up  by  Audit  Trail  Documentation.  Because  of  this,  existing  Program 
Documentation  seldom  reflects  the  true  nature  of  the  program  that  it 
describes . 
Panel   Member : 

The      Social      Security     Administration     has      a     Customer     Billing   System  that 
maintains   a   log   of  what    systems    are   being   used   and   by  whom. 
Panel    Conclusion : 

The  Maintenance  Manual  lends  itself  possibly  to  assist  in  assuring  that 
changes  are  properly  documented.  It  also  assists  in  exploring  the 
ramifications  of  a  pending  modification.  However,  without  rigid  procedures 
on  posting  all  changes  to  it,  the  Maintenance  Manual  would  soon  become 
obsolete. 


Base  Documentation,  a  list  of 
ase,      and     what      fields  they 

Panel   Member : 

There  is  currently  provision  for  the  identification  of  all  software 
(computer  programs)  which  access  the  Data  Base  (see  section  2.2  of  the  Data 
Base  Specification).  As  can  be  seen,  this  provision  does  not  identify  which 
programs  access  which  fields.  This  identification  could  be  handled  by 
section  3.C  of  the  Data  Base  Specification,  when  describing  the  Logical 
Characteristics  of  Fields.  However,  the  maintenance  of  such  a  cross 
reference  list  should  be  handled  through  an  automated  system  rather  than  a 
manual  system.  FIPS  Task  Group  17  is  now  developing  guidelines  for  Data 
Resource  Directories,  which  will  address  the  issue  of  relationships  between 
data   and    the   processes   which   work   upon  it. 


Question : 

Is      there      a   provision   to    include,    in   the  Data 
what   programs   are   allowed    to   access    the   data  b 
access? 


Ques  t  ion : 

Of  the  10  documents,  how  many  should  be  used  to  retrofit  existing  programs? 
Is    it   practical    to   retrofit   documentation   of   on-going  programs? 


Panel   Member : 

There  is  no  general  rule  for  determining  which  documents  should  be  used,  or 
the  level  of  detail  to  be  recorded  for  each.  This  is  determined  by  the 
needs  of  the  individual  organization.  It  is  advisable  that  an  organization 
consider  each  existing  program,  independent  of  all  others,  when  determining 
the  amount  of  documentation  to  capture.  Because  of  basic  differences  among 
programs    (e.g.,    o n e- t ime - s ho t ,    large   size,    frequently     used,      no      longer  in 
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operation,      volatile      coding   changes,    etc.),    some   programs  will   require  more 
documentation   than  others. 
Panel   Member : 

High      level     management   at    SSA  decided    to   rewrite   its   payroll    system,  rather 
than   produce   the   necessary   documentation   for   an   existing  system. 
Panel   Member : 

Every     organization     will   most    likely   encounter   considerable   resistance  from 
analysts    and     programmers      concerning      the      retrofit      of     documentation  for 
existing  programs. 
Panel   Member : 

Typically,      management      does   not   know  what    they  want.      Good   documentation  is 
the   physical    evidence   of  what    they  require. 
Panel   Member : 

Third      generation     equipment      eliminates      the     need    for   some   of    the  manually 
produced   documentation   previously     prepared      (e.g.,      Operations      and  User's 
Manu a  1 s  )  . 
Pane  1   Member  : 

The     burden     of     documentation      is      a     problem      for    internal   ADP  management, 
whereas    user   management    is    unaware    that    a    problem      concerning  documentation 
exists  . 
Panel   Member : 

User  management  is  often  insensitive  to  the  need  for  documentation,  and, 
typically,  does  not  clearly  spell  out  the  application  problem,  or  what  their 
ADP    requirements    actually  are. 

Question : 

How  do  you  convince  the  interactive  on-line  user  to  read  and  follow  the 
User's  Manual? 


Panel   Member : 

Typically,  the  interactive  on-line  user  will  not  read  documentation  that 
exceeds  one  page  in  length.  Therefore,  this  necessitates  having  the  user 
documentation  on-line  and  readily  available  to  the  user  in  a  s e 1 f - t each ing 
mode    (e.g.,    HELP  modules). 


Ques  t  ion : 

Isn't  FTPS  PUB  38,  especially  the  User's  Manual,  directed  toward  second 
generation   computer  systems? 


Panel   Member  : 

Many     parts      of      FIPS   PUB   38   are   oriented    to,    or      thought   of   as   being  second 
generation.      In   fact,    FIPS   PUB    38   has    its      historical      origin      in      the  mid- 
1960's,    when   second   generation   equipment   was    in  prominence. 
Panel   Member  : 

It  is  very  difficult  to  prepare  a  standard  or  guideline  that  would  be 
applicable  to  all  on-line  interactive  systems  having  various  levels  of 
sophistication.  Special  purpose  manuals  that  support  the  particular  on-line 
system  should  be  prepared  in  hardcopy  or  softcopy  form  to  supplement  the 
User's  Manual.  For  on-line  systems,  the  User's  Manual  could  satisfy  the 
documentation  needs   of   top    level   management   of   the   user  organization. 


Question  : 

Have  you  experienced  any  difficulties  with  the  Data  Requirements  Document  as 
it    applies    to   on-line  systems? 

Panel   Member : 

No,  because  the  Data  Requirements  Document  is  developed  around  requirements, 
not   programs   or  hardware. 

Question : 

Who  is  the  author  of  these  documentation  manuals,  the  programmer  or  the 
analyst? 


47 


Panel  Member : 

Depending     upon     the     environment     of  the  organization,   either  programmer  or 
analyst  could  be  the  author. 
Audience  Comment : 

Some  companies  have  quality  assurance  groups  that  employ  writer/editors  to 
confer  with  the  programmer/analyst  and  actually  prepare  the  documentation 
for  the  program/  system.  The  assumption  is  made  that  if  programmers  cannot 
explain  the  system  to  an  editor  well  enough,  then  the  editor  cannot  document 
it.     In  addition: 

1,  The  editor   is  a  better  writer. 

2,  Analysts   can  devote   their   time   to   Systems  Analysis   and  Design. 

3,  Programmers  can  devote  their  time  to  programming, 

4,  The  entire  operation  is  more  cost-effective. 

5,  Having   to  explain  processes  to  a  third  party  leads  to  better 
design  through  structured  thinking. 


Quest  ion : 

How  would  software  contractors  react  to  the  inclusion  of  a  standard 
documentation  like  FIPS  PUB  38  as  part  of  the  deliverables  under  a  software 
contr ac  t . 


Panel  Member; 

Pips  pub  38  would  be  acceptable  for  second  generation  type  equipment,  but 
the  contract  would  have  to  be  explicit  about  which  documents,  and  which 
items  within  them,  should  be  included,  and  how  they  relate  to  the  system 
being  developed. 

Que  s  t  ion : 

Would  FIPS  PUB  38   be  applicable   to   small   dedicated  mini-computer  systems? 
Panel  Member : 

Absolutely,  since  dedicated,  departmental,  mini-computer-based  systems 
typically  resemble  late  first  generation  or  early  second  generation  computer 
systems,   for  which  FIPS  PUB  38   is   ideally  suited. 

Que  s  t  ion ; 

FIPS  PUB  38  attempts  to  define  what  is  minimum  documentation.  Has  the 
Social  Security  Administration  established  what  they  feel  is  too  much 
documentation   for  different  circumstances? 


Panel  Member : 

SSA     has  not   established  any  general   guidelines,    to  be   followed  by  those  who 

develop   systems,   on  what   is   too  much  and  what   is   too     little.        However,  we 

are  attempting  to  determine  documentation  requirements  by  requesting  our 
four  applications  divisions   to  gather   all   available  documentation  together, 

and  to  compare  it  to  FIPS  PUB  38.  Then  we  ask  them  to  comment  on  the  ten 
document   types   as  being   C-Complete,    I-Incomplete ,   or   NA-Not  Applicable, 

Quest  ion : 

Does  the  Program  Maintenance  Manual  present  an  overall,  detailed  picture  of 
the  System  for  the  analyst,  who  has  to  determine  what  ramifications  a  given 
change  will  have   on   the  entire  system? 

Panel  Member , 

No,  because  the  Program  Maintenance  Manual  is  intended  to  present  a  detailed 
description  of  a  given  program;  not  the  entire  system.  Perhaps,  if  the 
functional  requirements  document  and  the  system/  subsystem  specification 
were  kept  up-to-date,  they  could  be  used  to  determine  the  impacts  of 
changes , 

Panel  Member: 

A  cross-reference  grid  showing  the  relationships  between  programs  and  data 
element s/ items   could  be     prepared     to     supplement     the     Program  Maintenance, 
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Ques  t  ion : 

Does  anyone  prepare  and  maintain  their  documentation  using  interactive  text 
editing  systems? 

Panel  Member : 

Yes,  SSA  currently  does  some,  and  will  be  receiving  additional  equipment  to 
expand   this  effort. 

Ques  t  ion ; 

There     appears   to  be  a   lack  of  und 
contents  of  FIPS  PUB   38.     What  do 
should   information  be  described? 

Panel   Member : 

The  first  two  documents  that  are  created  in  an  organization  are  hard  to 
produce,  and  require  a  great  learning  process.  Each  organization  will  have 
to  develop  its  own  interpretation  of  the  content  of  each  document,  and  the 
degree   of   detail   to   be   described    for  each. 

Ques  tion : 

The  contents  of  similar  sections  of  many  of  the  documents  seem  to  capture 
redundant  information  (e.g.,  Operating  Environment  is  specified  in  both  the 
Functional  Requirements  Document  and  the  System/Subsystem  Specification), 
Was   this  deliberate? 


erstanding,  or  a  misinterpretation,  of  the 
"paragraphs"     mean,     and     to     what  extent 


Panel  Member : 

Yes,  information  has  been  included  in  each  document  to  provide  a  "stand- 
alone" understanding  of  the  document,  with  a  minimum  need  for  cross- 
referencing  to  parts  of  other  documents  that  may  have  been  produced. 
However,  it  would  be  perfectly  valid  to  set  up  the  documentation 
requirements  in  your  organization  so  that  information  is  captured  only  once 
in  a  specific  document,  or  once  in  a  specific  section  of  the  overall 
documentation  which  your  organization  records  for  a  given  Automated  Data 
Sys  tem . 
Panel  Member : 

Each  organization  would  have  to  develop  guidelines  and  examples  to  follow  in 
the  preparation  of  documentation.  FIPS  PUB  38  was  not  intended  to  be  a 
stand-alone  document. 


SUMMARY 

1.  Are  the  guidelines  general  enough  in  scope?  No,  to  a  large  extent  they 
are  obsolete,  since  the  batch  orientation  is  much  too  strong  and  real  time, 
on-line   systems   are   not   adequately  addressed. 

2.  In  terms  of  the  abstraction  of  the  documentation  standard,  there  is  a 
good  deal  of  ambiguity,  and  a  need  for  interpretation  at  the  lower  levels. 
FIPS  PUB  38  should  not  be  issued  without  internal  guidelines,  or  else  its 
implementation  would   be    left   up   to   each  individual. 

3.  Are  guidelines  comprehensive  enough?  It  provides  for  adequate 
documentation  in  those  situations  for  which  it  was  intended,  but  there  is 
some   question   about    its  maintainability. 


4.  What  kind  of  familiarization  training  and  division  of  responsibility  is 
best  for  doing  documentation?  It  appears  that  using  a  documentation 
specialist  or  tech  writer,  who  is  not  a  programmer  or  systems  analyst,  may 
be   the   best   way   to   go    for   quality  documentation. 

5.  The  areas  of  System  Level  Maintenance  Manual  needs  to  be  addressed^ 
along  with   the    tools    for   se 1 f -document ing   on-line   query  systems. 
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INTRODUCTION:    "STANDARDS,    TRAINING,    POLICY,    AND   AUDIT  PERSONNEL" 


Harris   G.  Reiche 
Director,   Office  of  ADP  and   Telecommunications  Management 
Department   of   the  Interior 

Welcome  to  Session  C.  Now  that  there  is  a  FIPS  PUB  38,  what  do  you  do  with 
it?  We  will  be  addressing  that  question  from  the  standpoint  of  agency  staff 
function.  More  specifically,  for  you  who  are  the  agency  standards  managers, 
or  responsible  for  agency  ADP  policy,  do  you  turn  the  guideline  into  a 
standard?  Do  you  use  it  only  as  a  guideline?  Do  you  leave  that  decision  to 
your  bureau  or  other  subordinate  organizations?  Or  even  to  operational 
management  for  your  decentralized  programming  functions?  How  do  you  handle 
training  throughout  your  agency?  Whatever  your  decision  is  with  respect  to 
the  foregoing  questions,  how  do  you  maintain  follow-up  to  assure  good 
doc  um  entation? 

How  should  the  auditing  staff  use  FIPS  PUB  38?  How  important  is  use  of  the 
guidelines  to  the  success  of  application  programs  in  meeting  their 
objectives?  How  can  the  auditor  improve  his  performance  by  using  the 
guideline?  Of  course  there  is  no  single  answer  to  any  of  these  questions. 
It  is  unlikely  that  we  could  even  get  agreement  among  the  panel  members.  It 
isn't  the  intention  of  this  panel  to  develop  a  canned  approach  to 
implementing  FIPS  PUB  38,  but  to  stimulate  a  discussion  of  the  issues--to 
exchange   the   approaches   being    taken  by  various  agencies. 

The  format  of  the  session  will  include  presentations  from  three  panel 
members,    followed   by  a   discussion   among    the   panel   members   and   the  audience. 

The  first  panel  member,  Mike  Gall,  from  the  Civil  Service  Commission,  will 
address  some  of  these  issues  from  the  perspective  of  a  relatively  small 
government  agency — where,  to  a  great  extent,  the  ADP  line  and  staff 
organization   is    the  same. 

The  second  panel  member  is  Joe  Strnad,  from  the  Department  of  Health, 
Education,  and  Welfare,  He  will  discuss  the  issues  from  the  perspective  of 
a  large  agency,  with  large,  and  often  times  autonomous  subordinate 
organizat  ions , 

The  third  panel  member,  Phil  Morrison,  is  from  the  Department  of  Housing  and 
Urban  Development.  He  will  review  FIPS  PUB  38  from  the  auditor's 
perspective. 

The  fourth  panel  member,  Roy  Young,  from  Health,  Education,  and  Welfare,  was 
a  member  of  Task  Group  14,  which  developed  FIPS  PUB  38.  He  will  participate 
in   the   discussions    following   the    three  presentations. 
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FIPS   PUB   38  - 


-   IMPLEMENTATION   PHILOSOPHY    IN   THE   DEPARTMENT   OF  HEALTH, 
EDUCATION   AND  WELFARE 


Joseph   J.  Strnad 
Department   of  Health,    Education   and  Welfare 
Office  of  Management  Technology 
200   Independence  Avenue,  S.W, 
Washington,    D.    C.  20201 


Before  addressing  the  questions  specified  for  discussion  by  this  panel,  I 
will  first  cover  the  uses  being  made  of  FIPS  PUB  38  at  the  present  time  in 
this  Department;  and  then  discuss  how  we  propose  to  integrate  the 
documentation  concepts  contained  in  the  publication  into  our  ADP  operations. 
Hopefully,  this  will  explain  our  concept  of  how  staff  persons,  such  as 
assembled  here  today,  can  directly  influence  the  documentation  process  in 
their  departments,  in  a  manner  consistent  with  overall  management 
objectives. 

As  most  of  you  know,  HEW  consists  of  several  components,  with  distinctive 
missions  and  varied  historical  backgrounds.  We  have  organizations  that  have 
been  around  for  a  long  time,  such  as  the  Social  Security  Administration 
(SSA),  the  Public  Health  Service  (PHS),  and  the  Office  of  Education  (OE); 
and  relatively  new  organizations  like  the  Office  of  Civil  Rights  (OCR)  and 
the  Office  of  Human  Development  (OHD).  Needless  to  say,  the  older 
organizations  have  established  documentation  practices  set  forth  in  systems 
manuals  and  standards.  Depending  upon  the  quality  of  such  manuals,  these 
agencies  are  finding  FIPS  PUB  38  useful  in  different  ways.  For  example,  the 
Bureau  of  Data  Processing  of  SSA  is  revising  their  operations  manual,  using 
FIPS  PUB  38  as  a  guide.  The  PHS  is  developing  a  standards  manual,  based  on 
FIPS  PUB  38,  for  use  by  their  various  component  agencies.  OE ,  on  the  other 
hand,  published  their  ADP  systems  manual  in  September,  1975,  which  had  a 
chapter  on  documentation  which  is  very  similar  to  FIPS  PUB  38,  since  it  was 
partly  based  on  the  ANSI  publication  "Technical  Documentation  of  Computer 
Projects".  Our  newer  organizations,  like  OHD,  have  no  documentation 
manuals,  and  have  found  FIPS  PUB  38  useful  in  specifying  requirements  to 
contractors    for   new   systems   development  efforts. 

When  FIPS  PUB  38  was  issued  in  February,  1976,  we  at  the  department  level 
recognized  that  it  would  have  value  in  varying  ways  among  our  componen t s , gnd 
experience  to  date  has  confirmed  that  belief.  We  gave  the  publication  broad 
distribution  in  the  department  -  around  800  copies,  but  recognized  that  it 
would  take  a  long  time  to  realize  any  appreciable  impact,  A  principal 
reason  for  not  mandating  its  use  was  the  simple  fact  that  revision  of 
documentation  manuals  and  guides  requires  resources  which  may  not  be 
available  in  the  agencies'  budgets.  Also,  agencies  have  their  own 
priorities,  and  may  have  requirements  that  rank  above  a  major  overhaul  of 
documentation  practices,  particularly  if  they  already  have  a  manual  or 
established  practices  which  they  consider  reasonably  satisfactory.  In 
short,  we  in  HEW  distributed  FIPS  PUB  38  as  a  guideline,  to  be  used  as 
deemed   appropriate   by   its  recipients. 

However,  we  did  not  let  the  matter  rest  there.  We  at  the  department  level 
recognized  the  need  to  assure  that  all  components  in  the  department  should 
strive  toward  a  level  of  documentation  to  achieve  the  goal  of  FIPS  PUB  38  - 
namely  "to  provide  information  to  suppport  the  effective  management  of  ADP 
resources   and    to    facilitate    the    interchange   of  information". 

Last  spring,  we  launched  an  overall  ADP  systems  management  study  project 
designed  to  lead  to  departmental  policy  regarding  life  cycle  system 
management,  from  the  planning  and  budgeting  phase  through  the  operations 
phase.  Areas  under  study  are:  systems  categories,  approval  levels, 
monitoring,      operational    reviews,    as   well    as   system  documentation  within  the 
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software  life  cycle.  While  our  initial  concepts  on  documentation  do  not 
exactly  coincide  with  FIPS  PUB  38,  we  have  found  it  a  useful  guide  in  our 
deliberations.  In  a  few  weeks,  we  will  be  convening  a  departmental  task 
force  to  review  the  various  comments  we  have  received  from  our  components, 
and  to  finalize  our  life  cycle  systems  management  concepts  and  policie*.  It 
is  our  objective  to  establish,  within  those  policies,  the  requirements  for 
documentation  related  to  departmental  AD?  management.  Again,  this  is  a 
long-term  proposition,  but  we  feel  it  holds  promise  of  bringing  all 
components  into  some  degree  of  harmony  regarding  system  documentation.  It 
is  very  doubtful,  in  an  organization  as  large  as  HEW,  that  we  will  ever 
achieve  uniform  documentation  throughout  —  but  we  should  strive  for  basic 
similarity,  with  minimum  standard  requirements,  to  facilitate  exchange  and 
use  of  data  and  systems.  FIPS  PUB  38  provides  a  common  benchmark  for  this 
to  occur   throughout   the   federal  establishment. 

In  the  near  term,  I  think  the  philosophy  underlying  the  standard  can  be 
promulgated   in   two  or   three  different  ways; 

First,  I  think  the  FIPS  PUB  38  should  be  required  reading  by  all 
professionals  in  the  ADP  business.  Every  professional  should  be  familiar 
with  the  family  of  documents  in  the  publication  and  the  suggested  content 
and   structuring  of   the  documentation. 

Second,  FIPS  PUB  38  should  be  required  reading  at  the  level  within 
organizations  where  the  responsibility  rests  for  maintaining  in-house  ADP 
procedures,  including  documentation.  It  should  be  maintained  as  a  ready 
reference.  If  the  organization's  systems  manual  is  under  revision,  and  the 
use  of  FIPS  PUB  38  guidance  is  a  feasible  alternative,  it  should  be 
followed.  By  this  means,  we  can  gradually  evolve  toward  a  uniform  standard 
for  documentation. 

Lastly,  managers  of  programs  responsible  for  approving  new  system 
development  efforts  should  have  a  general  awareness  of  the  documentation 
appropriate  for  various  phases  in  the  software  life  cycle.  This  will  tend 
to  make  them  more  prone  to  support  the  resource  requirement,  and  also,  it 
will  give  them  some  idea  where  answers  can  be  found  to  their  system 
questions.  We  in  HEW  feel  strongly  that  program  managers  being  supported  by 
ADP  systems,  if  they  are  to  get  their  money's  worth  from  the  resources  they 
are  investing  in  systems,  must  develop  an  awareness  of  ADP  systems  and  what 
makes    them   tick.      FIPS   PUB   38    is    a   good   primer    for   this  purpose. 

We  in  HEW,  as  a  corollary  feature  of  life  cycle  management,  plan  to  conduct 
review  and  evaluation  of  selected  systems.  In  addition  to  evaluating  system 
performance  against  requirements,  we  intend  to  inspect  the  adequacy  of 
system  documentation  to  support  the  system,  as  another  measure  of  system 
performance.  We  would  expect  to  find  documentation  that  approaches  the  FIPS 
PUB  38  specifications,  or  something  reasonably  adequate,  in  lieu  thereof. 
Accordingly,  FIPS  PUB  38  will  serve  as  a  basic  checklist  in  this  review  and 
evaluation  undertaking. 

To  summarize,  we  in  HEW  have  not  legislated  across-the-board-compliance  with 
FIPS  PUB  38,  but  are  making  some  progress  toward  its  goal  of  better  overall 
documentation   of   computer   programs   and   automated  systems. 
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THE   ROLE   OF   AUDITORS    IN   THE   DEVELOPMENT   AND   EVALUATION   OF   AUTOMATED  SYSTEMS 


Phillip  L.  Morrison 
Office  of   Inspector  General 
Department   of  Housing   and   Urban  Development 
Office   of  Audit 
451     7th   Street,    SW  —  Room  8284 
Washington,    D.    C.  20410 


Si.  ce  most  of  you  are  not  auditors,  I  would  like  to  start  by  defining  the 
role  of  auditors,  both  internal  and  external,  in  the  development  and 
evaluation  of  computer  programs  and  automated  systems.  Then,  I  will  address 
the  effect  documentation  has  on  auditors,  and  comment  on  the  impact  I  expect 
FIPS   PUB   38    to  have   on  auditors. 

For  the  purpose  of  this  discussion,  I  will  define  internal  and  external 
audit  very  narrowly.  I  define  external  audit  as  an  audit  group  independent 
of  the  Department  or  Agency,  Since  we  are  dealing  with  the  Federal 
Government,  most  external  auditing  is  performed  by  the  General  Accounting 
Office.  I  define  internal  audit  as  an  audit  group  within  the  Department  or 
Agency,  but  independent  of  the  part  of  the  organization  responsible  for  the 
development   of   computer   programs   and   automated  systems, 

I  realize  that  most  of  the  technical  audits  of  computer  programs  and 
automated  data  systems  are  performed  by  audit  groups  within  data  processing 
organizations.  I  do  not  mean  to  discourage  or  belittle  this  approach,  but 
it  is  part  of  the  development  process,  not  a  totally  independent  review  or 
analysis,    and   my   talk   addresses    independent  audits. 

Since  I  spent  almost  ten  years  with  the  General  Accounting  Office  (GAO) 
before  joining  HUD,  I  think  that  I  can  give  a  fair  explanation  of  the  role 
of  GAO.  As  you  know,  we  expected  to  have  Dr.  Carl  Palmer,  who  is  currently 
with   GAO,    here   with   us  today. 

General   Accounting  Office 

GAO  has  been  active  in  the  area  of  ADP  for  many  years,  Mr.  Puckorius  has 
already  mentioned  GAO ' s  involvement,  and  you  will  find  a  reference  to  the 
1974  GAO  Report  on  Documentation  on  the  inside  cover  of  FIPS  PUB  38.  I  have 
that  report,  and  several  other  GAO  reports,  pamphlets,  and  guides  dealing 
with   ADP    for   any  of   you   that   may  want    to    look   at  them. 

One  of  the  GAO  publications  that  I  brought  is  titled  "STANDARDS  FOR  AUDIT  OF 
GOVERNMENTAL  ORGANIZATIONS,  PROGRAMS,  ACTIVITIES  &  FUNCTIONS."  This 
pamphlet  prescribes  the  standards  applicable  to  both  internal  and  external 
audits  of  the  Government.  A  basic  premise  of  these  standards  is  that  "the 
term  audit  is  used  to  describe  not  only  work  done  by  accountants  in 
examining  financial  reports,  but  also  work  done  in  reviewing  (a)  compliance 
with  applicable  laws  and  regulations,  (b)  efficiency  and  economy  of 
operations,    and    (c)   effectiveness    in   achieving   program  results." 

Another  is  an  exposure  draft,  which  GAO  is  currently  circulating  for 
comments,  "GUIDE  FOR  RELIABILITY  ASSESSMENT  OF  CONTROLS  IN  COMPUTERIZED 
SYSTEMS  (FINANCIAL  STATEMENT  AUDITS)."  This  draft  is  essentially  a 
questionnaire,  which  provides  auditors  with  a  rapid,  but  crude,  evaluation 
of   internal  controls. 

I  believe  that  a  great  deal  of  the  confusion  concerning  the  role  of  auditors 
is  due  to  the  fact  that  GAO  has  two  roles.  While  GAO  is  primarily  an 
auditing  organization,  it  also  has  the  responsibility  to  prescribe  the 
principles  and  standards  of  accounting  for  the  Federal  Government,  and  to 
approve  the  accounting  systems  used  by  Federal  Departments  and  Agencies. 
The   GAO     Manual      for      the     Guidance     of     Federal     Agencies      prescribes  both 

53 


accounting  requirements  and  the  procedures  necessary  to  obtain  approval  of 
an  accounting  system.  The  manual  outlines  some  minimal  documentation 
requirements  for  automated  accounting  systems,  and  refers  to  separate  review 
guides  which  GAO  uses   in   the  approval  process. 

GAO  has  issued  three  review  guides  which  agencies  must  complete  and  submit 
with  requests  for  approval  of  accounting  systems.  These  review  guides  cover 
the   following  areas: 

ACCOUNTING    SYSTEMS  DESIGN 

ACCOUNTING    SYSTEMS    DESIGN;    ADP  APPLICATIONS 
PAYROLL   SYSTEMS  DESIGN 


The  review  guides  are,  essentially,  questionnaires  which  deal  with  internal 
controls  and  audit  trails.  An  agency  must  answer  specific  questions 
identifying  the  controls  in  an  automated  system,  and  provide  specific 
references  to  the  documentation  of  the  controls.  I  have  copies  of  these 
questionnaires   available,    if  any  of  you  care   to   review  them. 


GAO     approval     of  accounting   systems   is   based   entirely  on  documentation,  and 

the   review  guides   are  used   in   lieu  of   imposing  documentation  standards.  GAO 

encourages     agencies     to     use     the     review     guides     during     the     design  and 

development   of  automated   systems   that   require   approval.      But,   GAO     does  not 

start     reviewing     a     system     until     the   agency  submits   the   documentation  and 

review  guides,  and  requests  a  review.  This  GAO  review  is  strictly  for 
approval  purposes,   and  will   not   result   in  an  audit  report. 


Most  of  you  are  probably  familiar  with  GAO  because  of  GAO's  auditing.  Since 
GAO  auditors  require  compliance  with  the  principles  and  standards  of 
accounting  prescribed  by  GAO,  I  can  understand  the  common  view  that  auditors 
require  the  inclusion  of  internal  controls  and  audit  trails.  The 
distinction  that  I  would  like  you  to  understand  is  that  GAO  does  not 
prescribe  principles  and  standards  of  accounting  as  part  of  its  auditing 
role. 


Internal  Auditors 

Internal  audit  organizations  do  not  have  a  responsibility  to  prescribe 
principles  and  standards  of  accounting  —  consequently,  they  do  not  normally 
prescribe     any     requirements      for  either   documentation  or   internal  controls. 

When  internal  auditors  review  an  automated  system,  the  primary  goal  is, 
usually,  to  determine  if  the  system  is  performing  its  function  accurately. 
This  determination  requires  an  analysis  of  the  internal  controls  in  the 
system,  and  controls  are  identified  by  reviewing  documentation,  the  subject 
of  FIP$  PUB  38.  A  review  of  internal  controls  requires  two  separate 
determinations:  (1)  Did  the  user  identify  the  controls  necessary  to  comply 
with  applicable  statutes,  regulations  and  policies?  (2)  Did  the  ADP  staff 
implement  all  of  the  requirements  specified  by  the  user,  and  all  controls 
necessary   for   accurate   functioning  of  any  automated  system? 

If  you  think  that  you  are  adding  controls  to  automated  systems  for  auditors, 
you  should  review  the  purpose  of  the  controls.  The  user  should  be  far  more 
interested  in  the  accuracy  of  any  automated  system  than  the  auditors.  After 
all,  auditors  may  look  at  a  system  occasionally  or  periodically,  but  users 
rely  on  it  every  day  to  get  their  job  done.  Users  and  developers  must  share 
the  responsibility  for  the  development  of  accurate  automated  systems. 
Auditors  also  have  a  responsibility  in  this  area,  but  the  audit 
responsibility  is  secondary,  and  it  in  no  way  diminishes  the  primary 
responsibility  of   the   users   and  developers. 

Ideally,  internal  auditors  should  be  involved  early  in  the  development  of 
automated  systems.  Mr.  Puckorius  stressed  this  in  his  presentation.  This 
approach  would  minimize  the  impact  of  any  problems  auditors  identify. 
Unfortunately,    early   involvement    is   easier   said    than  done.      Those   of  you  who 
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are  auditors  are  aware  of  the  difficulty  involved  in  trying  to  review  a 
system  during  the  development  process.  Unless  documentation  is  complete  and 
current,  and  designed  to  identify  internal  controls,  an  audit  of  this  type 
will  require  a  lot  of  audit  resources,  and  produce  no  visible  product.  The 
easy  alternative  for  the  auditors  is  to  let  the  review  slip  until  the  system 
is  developed.  Then  the  auditors  can  look  at  finished  documentation,  review 
the  GAO  questionnaires,  if  required,  and  analyze  the  acceptance  testing 
performed  by  or  for  the  user.  The  auditor  can  use  a  test  deck  to  check  the 
functioning  of  the  program,  and  he  can  issue  a  deficiency  report  on  any 
problems   —   a   product    to    show   for  his  work. 

The  users  and/or  developers  of  automated  systems  could  help  internal 
auditors  to  review  systems  while  they  are  being  developed.  Both  of  these 
groups  know  that  it  is  easier,  faster,  and  less  expensive  to  design  a  system 
right  in  the  first  place,  rather  than  to  patch  an  operational  system  to  make 
it  accomplish  something  it  was  supposed  to  do  in  the  first  place.  But,  why 
invite  trouble?  How  many  of  us  would  go  out  of  our  way  to  invite  a  critical 
evaluation  of  our  work?  Besides,  the  people  responsible  for  developing 
systems  frequently  believe  that  auditors  will  place  additional  requirements 
on  them,  particularly  in  the  area  of  internal  controls.  If  so,  it  is  only 
because   others   did   not   do   their    job  right. 

GAO  and  0MB  have  both  taken  a  very  active  role  in  encouraging  internal  audit 
groups  to  evaluate  automated  systems  while  they  are  being  developed.  Two 
recent  GAO  REPORTS,  one  dealing  with  crimes  in  computer  based  systems,  and 
the  other  dealing  with  automated  decision  making  systems,  included 
recommendations  for  internal  auditors  to  be  involved  in  the  design,  testing 
and  operation  of  automated  systems.  Many  agencies  made  commitments  to  the 
Congress,  in  response  to  these  recommendations,  and  0MB  required  all 
agencies  to  address  these  recommendations  in  their  FY  1978  budget 
submissions.  The  Privacy  Act  has  placed  new  requirements  on  automated 
systems,  and  both  developers  «nd  auditors  are  currently  evaluating  their 
responsibilities  under  this  act.  I  think  it  is  safe  to  say  that  every  audit 
group  in  the  Government  has  either  already  started  to  get  involved  in  the 
development    of   automated    systems,    or   is   making   plans    to   do  so. 


Effects    of  Documentation 

Poor  documentation  can  be  compared  to  a  blindfold;  this  comparison  is  valid 
for  both  existing  systems  and  systems  under  development.  Poor  documentation 
will  increase  the  time  required  to  perform  an  audit,  and  decrease  the 
effectiveness   of  the  audit. 

Poor  documentation  will  conceal  some  of  the  deficiencies  in  a  bad  system,  at 
least   for  a   time  but,      it     will     also     hamper     any     efforts     to  correct 

deficiencies   that   do  surface. 


Good  documentation  is  an  invitation  for  critical  analysis.  If  the 
documentation  is  good  enough,  errors  will  stand  out  like  a  sore  thumb.  But, 
good  documentation  will  help  the  developer  avoid  errors  and  simplify  the 
correction   of  errors. 


Auditors  can  make  a  meaningful  contribution  to  the  development  of  automated 
systems,  but  only  if  documentation  is  kept  current,  and  internal  controls 
and  audit  trails  are  addressed  adequately.  Otherwise,  effective  audits  will 
be  feasible  only  after  the  system  becomes  operational.  Internal  audit 
groups  are  just  developing  the  ability  to  review  automated  systems.  We  face 
real  problems  allocating  the  time  of  the  few  people  who  are  qualified  to 
perform  this  work.  Unless  users  and  developers  work  with  us,  we  will  be 
forced  to  delay  our  reviews  until  after  the  systems  are  implemented.  This 
approach  will  let  us  review  more  systems  with  less  resources,  but  it  means 
modifying  existing  systems  to  make  them  do  the  things  they  should  have  been 
designed  to  do.  As  long  as  this  continues,  we  will  always  be  fighting  brush 
fires  not   an   efficient   or   cost-effective   approach     for  anyone. 
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I  have  tried  to  show  that  auditors  are  vitally  interested  in  both 
documentation  and  FIPS  PUB  38.  But,  the  impact  is  indirect,  since  auditors 
do  not  prepare  documentation  or  prescribe  system  requirements.  We  use 
documentation,  and  any  improvement  in  documentation  will  help  auditors.  I 
believe  FIPS  PUB  38  will  cause  a  big  improvement  in  the  documentation  of 
automated  systems.  The  documentation  required  by  FIPS  PUB  38  does  not  meet 
all  the  needs  of  auditors,  but  it  comes  closer  to  meeting  these  needs  than 
any  documentation  standards  that  I  have  seen  in  any  Federal  Department, 
outside  of  DoD.  I  hope  to  work  with  HUD's  standards  staff  in  the 
implementation  of   these  guidelines,    and   any  time  our  auditors   review  a 

computer  program  or  automated  system  we  will  use  and  evaluate  the  related 
documentation. 

The  documentation  guidelines  in  this  publication  may  meet  the  needs  of  the 
users  and  the  computer  professionals,  but  I  do  not  think  they  will  replace 
the  GAO  review  guides.  As  an  auditor,  I  would  like  to  see  the  area  of 
controls  addressed  separately,  to  assure  a  systematic  treatment  of  this 
important  area.  Auditors  realize  that  controls  cost  money,  and  the 
inclusion  of  any  redundant  or  unnecessary  controls  is  a  waste  of  money.  Our 
goal  is  to  include  the  minimum  number  of  controls  necessary  to  achieve  the 
required  accuracy.  The  GAO  review  guides  were  prepared  for  accounting 
systems,  where  every  effort  must  be  made  to  avoid  any  errors.  We  recognize 
that  this  degree  of  accuracy  is  not  required  in  all  automated  systems,  but 
it  is  very  disturbing  to  find  that  most  systems  are  developed  without  a 
systematic  approach  to  controls.  I  would  like  to  see  a  systematic  approach 
to  controlling  all  input,  processing  and  output;  this  would  insure  the 
placement  of  controls  as  early  in  the  system  as  possible,  and  the  avoidance 
of   redundant  controls. 

My  final  comment  on  FIPS  PUB  38  may  not  be  a  fair  criticism,  but  I  consider 
it  to  be  a  problem  that  these  guidelines!  address  only  the  automated  portion 
of  any  function.  When  auditors  review  an  area,  they  try  to  look  at  the 
entire  operation  from  beginning  to  end,  not  just  the  automated  portion.  I 
would  like  to  see  documentation  that  includes  an  entire  function,  including 
everything   that   takes   place  before  and   after   the  automated  portion. 
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SYNOPSIS   OF   QUESTIONS   AND   ANSWERS   FROM   PARALLEL   SESSION  C 


Fred   J.  Cole 
Public   Health  Service 


Edie  Lasner 
Office   of  Education 


Ques  tion : 

How  does   one    train  people   to   document?   Will    Civil    Service   offer   a  course? 
Young : 

Training  is  a  product  of  what  each  agency/person  expects.  FIPS  PUB  38  does 
not  address  training.  FIPS  Task  Group  14  has  talked  about  having  some  sort 
of  training,  but  nothing  is  planned  now.  While  the  Civil  Service  Commission 
has  classes  on  documentation,  they  are  not  necessarily  concerned  with  FIPS 
PUB  38. 
Strnad : 

Documentation  will  be  prepared,  with  or  without  training,  and  managers  must 
support  it.  Documentation  has  been  with  the  ADP  community  since  day  one,  so 
its     actual   needs   and/or   potential   needs    to  management   are  well  established. 


Ques  t  ion  : 

Will   OMB   enforce   FIPS   PUB   38  as 


standard    (i.e.    not   a  guideline)? 


Reiche : 

No.        FIPS   PUB   38   addresses   all    levels   of   document   actions    and    therefore  can 
be   utilized   as    an     outline     of      the      requirements.        Local     management  must 
determine      the      degree      that   FIPS   PUB   38   affects    any   particular  application. 
This   was    the    logic    in  making   it   a   guideline,    not   a  standard. 
Audience   Comment : 

Whether  one  uses  "Standards"  or  "Guidelines"  depends  on  the  diversity  of 
computer  applications. 

Que  8  t  ion : 

Wi 1 1  TG  14  assist  agencies  in  implementing  FIPS  PUB  38?  Are  examples  of 
documentation   and    forms   going   to   be  made    available   as  guidelines? 

Young : 

TG      14  has   no  specific   plans    for    such   assistance.      Examples   of  documentation 

and   forms   are  not    going   to   be  made   available.      However,    NASA  and   GSA,  among 

others,      have  examples      of     documentation     and      forms      which   conform   to  the 

guidelines    in  FIPS   PUB  38. 

Ques  tion : 

How  does  one  "force"  non-ADP  professionals  (e.g.  mathematicians)  to  use  FIPS 
PUB  38? 


Cole  : 

Show   such   people   how  documentation   is   beneficial    to  them. 
Gall  : 

Enforcement  is  possible  only  in  the  area  of  security  compliance 
people   are   "on   their   own  hook." 


Otherwise 


Question : 

Who  within  an  organization  is  responsible  for:  (1)  determining  the  scope  of 
documentation,    and    (2)   compiling   the  documentation? 

Gall  : 

( 1 )  The  project  team  leader  in  the  f unc  t  iona 1  area,  i.e.,  a  person  not  in 
the  ADP  standards  area,  but  one  who  follows  standards  developed  by  the 
standards  area.  This  is  so  whether  the  agency  is  small  or  large;  the 
participation  of  management  will  depend  on  the  complexity  and  size  of  the 
project.  (2)  The  systems  analyst.  Some  agencies  have  gone  so  far  as  to 
hire  technical  writers  to  develop  the  documentation  required  for  a  given 
sys  tem . 
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S  trnad ; 

Where  there  are  contractors,  the  contracts  must  specify  the  level  and 
complexity   of  documentation. 

Quest  ion : 

How,  at  the  Civil  Service  Commission,  did  you  get  project  leaders  in  the 
functional  areas  to  take  over  documentation?  At  GPO,  ADP  is  always  taking 
back   the  function. 

Gall  ; 

Adequate  resources  are  provided  in  the  functional  areas.  ADP  does  provide 
documentation  guidelines    and  help. 

Question: 

What  did  Mr.  Morrison  mean  by  "controls"  in  non- f inane ia 1  systems?  Are  you 
referring   to   normal   edit    criteria,    physical    controls,    or  what? 

Morr  ison : 

The   user   should   know  his   real   needs,    what    is    an   acceptable   product    to  him. 
Gal  1  : 

For  instance,  the  CSC  Recruiting  and  Examining  System  has  3  million 
potential  applicants  on-line  to  60  offices.  System  requirements  specified 
certain  privacy  constraints.  Auditors  reviewed  the  system  design  to 
determine  if  it  meets  the  users'  requirements.  Where  possible,  auditors  are 
in  on  the  development  of  the  design  specifications. 
Re  iche  : 

Auditors    are   concerned   not    just  with    financial   management    systems.      Now,  for 
example,    controls    are   concerned   with  privacy. 
Audience    Comment : 

Auditors        should        be      looking     at      technical      aspects      of     systems  during 
development.      They   should   be      looking     beyond     any      financial      and  security 
controls. 
Audience    Comment : 

Auditors  see  themselves  as  providing  feedback  to  management.  Management 
areas   looked   at   by  auditors: 

.    Try   to   determine    feasibility   of   the  system. 

.    What   are    the   objectives   and   how  will    they   be  met? 

.    Are    they  documented? 

.    Have   you   considered   alternatives,    or   were   you    locked  in? 
.    Have   you   thought   about  maintenance? 
Technical   areas   looked  at: 

.    Are    there    input/output    controls   and   edit  criteria? 
.   What    is/will   be   the    impact   of   the  system? 

.    If   the    system  goes    sour,    will    the   department   be  embarrassed? 
.   What   are    the   risks  involved? 
.  Security. 

My  Department   audits   only   about    5%   of    its   ADP  systems. 

Much  discussion  followed  on  who  should  have  the  audit  function  (ADP  or 
general  auditors);  also,  on  whether  auditors  should  have  ADP  training.  The 
session   ended  with   the    following    (typical)  question: 

Ques  t  ion : 

Why  was  the  requirement  for  record  counts  put  in  the  user  area,  not  ADP 
operations? 

Young : 

The     argument      goes   both  ways,    but    the   "new   school"   puts    such   control  checks 
in   the  user  area. 
Gall  : 

Quality   control    is    turned   back   to   the  user. 
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FIPS    TASK   GROUP    14  MEMBERSHIP 


FIPS  Task  Group  14  (Documentation  for  Information  Processing  Systems) 
prepared  FIPS  PUB  38  from  existing  guidelines,  standards,  and  practices  in 
Federal  agencies  and  other  institutions.  The  following  members  of  FIPS  TG 
14    (past   and   present)    contributed    to    its   development   and  publication. 

Ruth  Anderson,    National   Bureau   of  Standards 
Fred   J.    Cole,    Public   Health  Service 
Phillip   Diamond,    Veterans  Administration 
C.    L.    Eadie,    General    Services  Administration 
Elizabeth   Fong,    National    Bureau   of  Standards 
James   Gillespie    (Task  Group   Chairman),    Department    of    the  Navy 
D.    H.    Gridley,    NASA  Goddard    Space   Flight  Center 
Robert   R.    Hegland,  NAVCOSSACT 
Helena   Hood,    General    Services  Administration 
Mitchell    Krasny,    National   Technical    Information  Service 
Tom  Kurihara,    Department   of  Agriculture 
Edie   Lasner,    Office   of  Education 
Beatrice   Marron,    National   Bureau   of  Standards 
Robert   A.    Mattes,    Social    Security  Administration 
Carl   Palmer,    General   Accounting  Office 
Kenneth   Rodey,    National    Security  Agency 
G.    Joyce   Rosencranz,    National    Security  Agency 
Mark   Silverman,    U.    S.    Geological  Survey 
Roy   A.    Young,    Department   of   Health,    Education   and  Welfare 


SYMPOSIUM   PLANNING  COMMITTEE 

The  following  people  were  responsible  for  the  planning  and  organization  of 
the  Symposium  for  Documentation  of  Computer  Programs  and  Automated  Data 
Systems.  Their  plans  were  turned  into  reality  by  the  people  at  NBS  and  CSC 
who   earn   their   living   by   doing   this    sort    of  thing. 

Mark   Silverman    (Chairman)    U.S.    Geological  Survey 
Roy  A.    Young,    U.S.    Department   of   Health,    Education   &  Welfare 
Mitchell   A.    Krasny,    National   Technical    Information  Service 
Beatrice  Marron,    National    Bureau   of  Standards 
Fred   Rao,    U;S.    Civil   Service  Commission 
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